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Preface 


Intended Audience 

Programmers at all levels of experience can use this manual effectively. 

New users should start with Chapter 1 (Introduction to the VAX/VMS 
Debugger). It contains an overview of debugger features, a brief interactive 
tutorial on the debugger, and a summary of debugger commands. 

The debugger can be used with most VAX/VMS supported languages 
(language support is summarized in Appendix E). This manual emphasizes 
usage that is common to all or most languages. For additional information 
that is specific to a particular language, you should also refer to the 
documentation furnished with that language. 

Note that you can use the VAX/VMS debugger only to debug code in user 
mode. You cannot debug any code in supervisor, executive, or kernel modes. 
If you need to debug code in other than user mode, refer to the VAX/VMS 
Delta/XDelta Utility Reference Manual , which describes the VAX/VMS DELTA 
/XDELTA Utility. 


Structure of This Document 

This manual is organized in three parts: 

• Chapters 1 through 9 present task-oriented and conceptual information 
about the debugger. 

• Part II, which follows Chapter 9, is the Debugger Command Dictionary. 
It lists all debugger commands alphabetically and provides complete 
information on command format, parameters, and qualifiers, as well as 
examples of each command's use. 

• Part III, which follows the Command Dictionary, consists of appendices. 
These provide reference information on various topics such as predefined 
keypad-key functions, debugger support of specific languages, and so on. 


Associated Documents 

Information on compiling and debugging in a particular language may be 
found in the documentation furnished with that language. 

Information on the linking of programs and on shareable images may be 
found in the VAX/VMS Linker Reference Manual. 
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Conventions Used in This Document 


Convention 

Meaning 

[ret] 

A symbol with a one- to three-character 
abbreviation indicates that you press a key on 
the terminal, for example, 1 ret| . 

ICTRL/xl 

The phrase CTRL/x indicates that you must press 
the key labeled CTRL while you simultaneously 
press another key, for example, CTRL/C, CTRL/Y, 
CTRL/O. 

$ SHOW TIME 

05-JUN-1985 1 1:55:22 

Command examples show all output lines or 
prompting characters that the system prints 
or displays in black letters. All user-entered 
commands are shown in red letters. 

[expression] 

Square brackets indicate that the enclosed item 
is optional. (Square brackets are not, however, 
optional in the syntax of a directory name in a file 
specification.) 

file-spec, . . . 

Horizontal ellipsis within command syntax indicates 
that additional parameters, values, or information 
can be entered. 

$ TYPE MYFILE.DAT 

Vertical series of periods, or ellipsis, means either 
that not all the data that the system would display 
in response to the particular command is shown or 
that not all the data a user would enter is shown. 

quotation marks 
apostrophes 

The term quotation marks is used to refer to 
double quotation marks ("). The term apostrophe 
(') is used to refer to a single quotation mark. 
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Summary of Technical Changes 


The following technical changes have been made to the VAX/VMS Debugger 
since VAX/VMS Version 4.2. 

The debugger now supports VAX DIBOL and VAX SCAN. Appendix E 
contains a summary of debugger support for these languages. Refer to the 
DIBOL and SCAN documentation for complete information. 

In addition, the following debugger features and commands have been added 
and are fully documented in this manual. 

Several enhancements have been made to screen mode (see Chapter 8 and 
Appendix C): 

• There are four new display attributes to be used with the SELECT 
command: /INPUT, /ERROR, /PROGRAM, and /PROMPT. These give 
you the option of mixing various types of debugger output in a display, 
or directing different types of output to separate displays. 

• There is a new PROMPT built-in display. PROMPT shows the debugger 
prompt and your input and may be manipulated like other displays, 
within certain restrictions. 

• You can now divide display windows vertically. The SET WINDOW, SET 
DISPLAY, and DISPLAY commands have been changed accordingly. 

• There are some new built-in window definitions. In addition to the 
full height and width of the screen, the predefined windows include all 
possible regions that result from dividing the screen vertically into halves, 
thirds, quarters, and sixths, and horizontally into left and right halves. 

• The built-in symbols %PAGE and %WIDTH have been added. These 
specify the current screen height and width of the terminal. 

• A new MOVE command lets you move displays across the screen. 

• A new EXPAND command lets you expand and contract displays. 

• A new EXTRACT command lets you save screen displays into a file, or 
create a file with all the DEBUG commands necessary to re-create the 
current screen state at a later time. 

• All displays, except for register displays, are now dynamic by default. 
This means that, if you change the terminal screen height or width, 
display windows will be resized in proportion to maintain their relative 
dimensions. The new qualifier /[NOjDYNAMIC lets you control this 
feature when using the DISPLAY and SET DISPLAY commands. 

• The /[NOJPOP and /[NOJPUSH qualifiers have been added to the 
DISPLAY and SET DISPLAY commands. These qualifiers give you the 
option of either popping or pushing a display to the top or bottom of the 
display "pasteboard", to show or hide that display when you issue those 
commands. 











Summary of Technical Changes 


• The SHOW DISPLAY and SHOW WINDOW commands have been 
enhanced. You can now specify a list of parameters, wildcards, and the 
/ALL qualifier with these commands. 

• There are some new and changed keypad key definitions associated with 
screen mode (see Appendix B). 

Other new features and commands are as follows: 

• You can now debug shareable images. The SET IMAGE, SHOW IMAGE, 
and CANCEL IMAGE commands have been added. 

• The new SET ATSIGN command lets you establish a default file 
specification that the debugger will use when searching for command 
procedures. There is also a new SHOW ATSIGN command. 

• The new SET EDITOR command lets you establish an editor of your 
choice to be invoked by the EDIT command. There is also a new SHOW 
EDITOR command. 

• The new SHOW STACK command provides detailed information about 
the current call stack. 

• The /[NOJSHARE and /[NOJJSB qualifiers have been added to the 
SET BREAK, SET TRACE, and STEP commands. The [NOJSHARE 
and [NOJJSB parameter keywords have been added to the SET STEP 
command. These features let you qualify breakpoints, tracepoints, and 
the STEP mode. 

• The /TYPE qualifier has been added to the EXAMINE and DEPOSIT 
commands. The TYPE parameter keyword has been added to the 
SET TYPE command. This feature lets you influence the debugger's 
interpretation of data in untyped locations. 

• When the debugger searches for symbols, it now uses the default scope 
search list of 0,1,2,3, . . . n (see the description of the SET SCOPE 
command). 

• You can now invoke the debugger from your program by signalling the 
condition SS$_DEBUG (see Appendix D). 
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Introduction to the VAX/VMS Debugger 


This chapter introduces new users to the VAX/VMS Debugger. Section 1.1 
summarizes the debugger's features. Section 1.2 gets you started using the 
basic functions and commands. Section 1.3 orients you to the debugger 
commands by grouping them in general categories, along with short 
descriptions. 


1.1 Overview of the Debugger 

Suppose you have compiled and linked your program successfully. You 
now run the program and discover some error. For example, the program 
terminates prematurely, or goes into an infinite loop, or gives incorrect output. 
The VAX/VMS Debugger helps you locate such run-time programming or 
logic errors, also known as bugs. 

The debugger lets you observe and manipulate your program interactively as 
it executes. By issuing debugger commands at the terminal, you can 

• start, stop, and resume the program's execution 

• trace the execution path of the program 

• monitor selected locations, variables, or events 

• examine and modify the contents of variables, or force events to occur. 

• in some cases, test the effect of modifications without having to edit the 
source code, recompile, and relink 

These are the basic debugging techniques at your disposal. Once you are 
satisfied that you have found the error in the program, you can edit the 
source code and compile, link, and execute the corrected version. 

As you use the debugger and its documentation, you will discover variations 
on the basic techniques. You will also find that you can tailor the debugger 
to your own debugging style. The features of the debugger are summarized 
below. 


1.1.1 Functional Features 

Programming Language Support 

You can use the debugger with the following VAX/VMS supported languages: 
Ada, BASIC, BLISS, C, COBOL, DIBOL, FORTRAN, MACRO-32, PASCAL, 
PL/I, RPG, and SCAN. The debugger recognizes the syntax, expressions, data 
typing, and other constructs of a given language. If your program is written 
in more than one language, you can change from one language to another in 
the course of a debugging session. 
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Symbolic Debugging 

The VAX/VMS Debugger is a symbolic debugger. You can refer to program 
locations by the symbols you used for them in your program (the names 
of variables, routines, labels, and so on). You do not have to use virtual 
addresses to refer to memory locations. 

Support for All Data Types 

The debugger understands all language data types, such as integer, floating 
point, enumeration, record, array, and so on. It displays program variables 
according to their declared type. 

Flexible Data Format 

The debugger permits a variety of data forms and types for entry and display. 
By default, the source language of the program determines the format used 
for the entry and display of data. You can also impose other formats. For 
example, the contents of a program location may be entered or displayed in 
ASCII, hexadecimal, octal, or decimal notation. 

Starting and Resuming Program Execution 

You start and resume program execution with the GO or STEP commands. 
The GO command causes the program to execute until a breakpoint is 
reached, a watchpoint is modified, an exception condition occurs, or the 
program terminates. The STEP command lets you execute a specified number 
of lines or instructions, or up to the next instruction of a specified class. 

Breakpoints 

By setting breakpoints with the SET BREAK command, you can suspend 
program execution at specified locations and check the current status of your 
program. Rather than specify a location, you can also suspend execution on 
certain classes of instructions or on every source line. Also you can suspend 
execution on certain types of events, such as exceptions and Ada tasking 
events. 

Tracepoints 

By setting tracepoints with the SET TRACE command, you can monitor the 
path of program execution through specified locations. When a tracepoint 
is triggered, the debugger reports that the tracepoint was reached and then 
continues execution. As with the SET BREAK command, you can also trace 
through classes of instructions and monitor events. 

Watchpoints 

By setting a watchpoint with the SET WATCH command, you can cause 
execution to stop whenever a particular variable or other memory area has 
been modified. When a watchpoint is triggered, the debugger suspends 
execution at that point and reports the old and new values of the variable. 

Manipulation of Variables and Program Locations 

With the EXAMINE command, you can determine the value of a variable or 
program location. The DEPOSIT command lets you change that value. You 
can then continue execution to see the effect of the change, without having to 
recompile, relink, and rerun the program. 
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Evaluation of Expressions 

With the EVALUATE command, you can compute the value of a source- 
language expression or an address expression. You can specify expressions 
and operators in the syntax of the language to which the debugger is currently 
set. 

Control Structures 

You can use logical control structures (FOR, IF, REPEAT, WHILE) in 
commands to control the execution of other commands. 

Shareable Image Debugging 

You can debug shareable images (images that are not directly executable). 

The SET IMAGE command makes it possible for you to reference the symbols 
declared in a shareable image. 

Terminal Support 

The debugger supports all VT-series terminals and Micro VAX workstations. 


1.1.2 Ease of Use Features 

Online HELP 

Online HELP is available during a debugging session. Typing HELP at the 
debugger prompt lists all of the debugger commands and selected topics for 
which detailed online HELP is available. 

Source Code Display 

In all supported languages except MACRO, the debugger lets you display 
lines of source code during a debugging session. For MACRO, the 
code stream of the executing routine is decoded into assembly language 
instructions. 

Screen Mode 

In screen mode, you can display and capture various kinds of information 
in scrollable windows that can be moved around the screen and resized. 
Automatically updated source, instruction, and register displays are available. 
You can selectively direct debugger input, output, and diagnostic messages to 
displays. You can also create "DO" displays that capture the output of specific 
command sequences. 

Keypad Mode 

When you invoke the debugger, several commonly used debugger command 
sequences are assigned by default to the keys of the numeric keypad. Thus, 
you can enter these commands with fewer keystrokes than if you were to 
type them at the keyboard. You can also create your own key definitions. 

Source Editing 

As you find errors during a debugging session, you can use the EDIT 
command to invoke any editor available on your system. You specify the 
editor you wish with the SET EDITOR command. If you use the VAX 
Language-Sensitive Editor, the editing cursor is automatically positioned 
within the source file whose code appears in the screen-mode source display. 
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Command Procedures 

You can direct the debugger to execute a command procedure (a file of 
debugger commands) to recreate a debugging session, to continue a previous 
session, or to avoid typing the same debugger commands many times during 
a debugging session. You can pass parameters to command procedures. 

Initialization Files 

You can create an initialization file containing commands to set your default 
debugging modes, screen display definitions, keypad key definitions, symbol 
definitions, and so on. When you invoke the debugger, those commands will 
be executed automatically to tailor your debugging environment. 

Log Files 

You can record in a log file the commands you enter during a debugging 
session and the debugger's responses to those commands. You can use 
log files to keep track of your debugging efforts, or you can use them as 
command procedures in subsequent debugging sessions. 

Symbol Definitions 

You can define your own symbols to represent commands, address 
expressions, or values. 


1.2 Getting Started 

The way you use the debugger depends on several factors: the kind of 
program you are working on, the kinds of errors you are looking for, and 
your own personal style and experience with the debugger. This section 
explains the basic functions that apply to most situations. Additional details 
have been purposely left out so you can quickly get started. 

The following subjects are covered: 

• Starting and terminating a debugging session 

• Entering debugger commands and getting online HELP 

• Viewing your source code in screen mode and with the TYPE command 

• Controlling program execution with the GO, STEP, and SET BREAK 
commands, and monitoring execution with the SHOW CALLS, SET 
TRACE, and SET WATCH commands 

• Examining and manipulating data with the EXAMINE, DEPOSIT, and 
EVALUATE commands 

• Controlling symbol references with path names and the SET MODULE 
and SET SCOPE commands 

At the end of this section, a sample debugging session with a simple program 
illustrates how to locate an error and correct it. 

Language-specific examples are in FORTRAN, COBOL, or Ada. However, the 
general concepts are readily adaptable to other languages. 
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1.2.1 Starting and Terminating a Debugging Session 

To execute a program with the debugger, you first compile and link the 
program with the /DEBUG command qualifier. The following example shows 
how to use the /DEBUG qualifier with a COBOL program consisting of a 
single compilation unit named INVENTORY. 

$ COBOL/DEBUG/NOOPTIMIZE INVENTORY 
$ LINK/DEBUG INVENTORY 

The /DEBUG qualifier on the compiler command (COBOL in this case) causes 
the compiler to write the symbol records associated with INVENTORY into 
the object module, INVENTORY.OBJ. These records will permit you to use, 
in debugger commands, the names of variables and other symbols declared 
in INVENTORY. (If your program has several compilation units, you need to 
compile each unit that you wish to debug with the /DEBUG qualifier). 

Depending on the default behavior of the compiler command, the resulting 
object code may be optimized to reduce the size of the program and make 
it run faster. This may cause the contents of some program locations to 
be inconsistent with what you might expect from the source code. So, 
when using the debugger, it is best to compile your program with the 
/NOOPTIMIZE as well as /DEBUG qualifiers. 

The /DEBUG qualifier on the LINK command causes the linker to include 
in the executable image all symbol information that is contained in 
INVENTORY.OBJ. The qualifier also causes the VAX/VMS image activator 
to start the debugger at run time. (Again, if your program has several object 
modules, you may need to specify other modules in the LINK command). 

You can now invoke the debugger by issuing the DCL RUN command. The 
following example shows how the debugger identifies itself after you invoke 
it: 

$ RUN INVENTORY 

VAX DEBUG Version 4.4 

•/.DEBUG-1-INITIAL, language is COBOL, module set to ’INVENTORY’ 

DBG> 

The "INITIAL" message indicates that the debugger is initialized for a COBOL 
program and that the name of the main program is INVENTORY. The 
initialization sets up any language-dependent debugger parameters. The 
prompt (DBG> ) indicates that you can now enter debugger commands. 

To terminate a debugging session any time DBG> is displayed, type EXIT or 
press CTRL/Z: 

DBG> EXIT 

$ 

The dollar sign ($) prompt indicates that you are at DCL command level. 

If you need to interrupt a debugging session for any reason, press CTRL/Y 
to return to DCL level. This may be necessary if, for example, your program 
loops or otherwise fails to complete execution, or if you need to interrupt 
a debugger command that is still in progress. From DCL level, if you then 
type the CONTINUE command, you return to where you interrupted the 
debugging session. 
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If you interrupted because of an infinite loop, type the DCL DEBUG 
command instead. This will return you to the debugger prompt so that 
you can enter another command. For example: 

DBG> GO 


(infinite loop) 

|CTRL/y! 

Interrupt 
$ DEBUG 
DBG> 

The following message, displayed during a debugging session, indicates that 
your program has completed normally: 

•/.DEBUG-I--EXITSTATUS, is ’'/.SYSTEM-S-NORMAL, normal successful completion’ 

DBG> 


1.2.2 Entering Debugger Commands 

You can enter debugger commands any time you see the debugger prompt 
(DBG> ). To enter a command, type it at the keyboard and press RETURN. 
You can enter several commands on a line by separating the command strings 
with semicolons (;). As with DCL commands, you can continue a command 
string on a new line by ending the line with a hyphen (-), and you can 
abbreviate debugger commands and qualifiers to unique characters. Also, 
you can use the up-arrow and down-arrow keys to recall commands lines, 
and the left-arrow and right-arrow keys to position the cursor for editing the 
command line. 

Typing HELP gives online HELP on debugger commands and selected 
topics. For example, if you type HELP STEP, help on the STEP command is 
displayed. 

When you invoke the debugger, a few commonly used command sequences 
are automatically assigned to the keys on the numeric keypad (to the right of 
the main keyboard). By pressing keypad keys, you can enter these commands 
with fewer key strokes. The predefined key functions are identified in 
Figure 1-1. In addition to the STEP, GO, SHOW CALLS, and EXAMINE 
commands, several functions that manipulate screen-mode displays are bound 
to the keys. You can also redefine key functions with the DEFINE/KEY 
command. 

Most keypad keys have three predefined functions—DEFAULT, GOLD, and 
BLUE. To obtain the DEFAULT function, simply press the key. To obtain the 
GOLD function, first press the PF1 key then the given key. To obtain the 
BLUE function, first press the PF4 key, then the given key. In Figure 1-1, the 
DEFAULT, GOLD, and BLUE functions are listed within each key's outline, 
from top to bottom respectively. For example, pressing keypad key 0 enters 
the command STEP (DEFAULT function); pressing key PF1 and then key 0 
enters the command STEP/INTO (GOLD function); pressing key PF4 and 
then key 0 enters the command STEP/OVER (BLUE function). 

Normally, keys 2, 4, 6, and 8 let you scroll screen displays down, left, right, 
or up, respectively. By putting the keypad in the MOVE, EXPAND, or 
CONTRACT state (as indicated in Figure 1-1), you can also use these keys to 
move, expand, or contract displays in four directions. Type HELP Keypad to 
get HELP on the keypad key definitions. 
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Figure 1-1 Keypad Key Functions Predefined by the Debugger 
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1.2.3 Viewing your Source Code 

The easiest way to view your source code while debugging is to invoke screen 
mode, as described below. By default, when you invoke the debugger, you 
are in "noscreen" mode, which provides other techniques for viewing source 
code. Noscreen mode is described at the end of this section. 
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1.2.3.1 Screen Mode 

You invoke screen mode by pressing keypad key PF3 (or by typing SET 
MODE SCREEN). In screen mode, by default the debugger splits the screen 
into three displays named SRC, OUT, and PROMPT, as illustrated below: 

- SRC: module SWAP.ROUTINES -scroll-source- 

2: with TEXT.IO; use TEXT.IO; 

3: package body SWAP.ROUTINES is 
4: procedure SWAP1 (A,B: in out INTEGER) is 

5: TEMP: INTEGER; 

6: begin 

7: TEMP := A; 

-> 8: A := B; 

9: B := TEMP; 

10: end; 

11 : 

12: procedure SWAP2 (A,B: in out COLOR) is 

13: TEMP: COLOR; 

- OUT -output- 

stepped to SWAP .ROUT INES. SWAP 1.‘/.LINE 8 

SWAP.ROUTINES.SWAP1.A: 35 


- PROMPT -error-program-prompt- 

DBG> STEP 
DBG> EXAMINE A 
DBG> 

The SRC display shows the source code of the module (compilation unit) that 
is currently executing. An arrow in the left column points to the source line 
corresponding to the current location of the program counter (PC). The line 
numbers, which are assigned by the compiler, match those in a listing file. 

As you execute the program, the arrow moves down and the source code is 
scrolled vertically to center the arrow in the display. 

The OUT display captures debugger output from the commands that you 
enter. The PROMPT display shows the debugger prompt, your input, 
debugger diagnostic messages, and program output. 

Both SRC and OUT are scrollable so you can see whatever information may 
scroll beyond the display window's edge. Use keypad key 3 to select the 
display to be scrolled. Use keypad key 8 to scroll up and keypad key 2 to 
scroll down. Scrolling a display does not affect program execution. 

If the debugger cannot locate source lines for the currently executing module, 
it tries to display source lines in the next module down on the call stack for 
which source lines are available and issues the following message: 

'/.DEBUG-I-SOURCESCOPE, Source lines not available for . 0\y,PC. 

Displaying source in a caller of the current routine. 

Source lines may not be available for a variety of reasons: 

• The PC is within a system routine, or a shareable image routine for which 
no source code is available. 

• The PC is within a routine which was compiled without the /DEBUG 
compiler command qualifier (or with /NODEBUG). 

• The source file was moved to a different directory after it was compiled 
(the location of source files is embedded in the object modules). 


1—8 












Introduction to the VAX/VMS Debugger 


1.2.3.2 Noscreen Mode 

"Noscreen" mode is the default, line-oriented mode of displaying input and 
output. To get into noscreen mode from screen mode, press the keypad 
key sequence GOLD-PF3 (or type SET MODE NOSCREEN). In that mode, 
you can use the TYPE command to display one or more source lines. For 
example, the following command displays line 7 of the module that is 
currently executing: 

DBG> TYPE 7 
7: TEMP := A; 

DBG> 

The display of source lines is independent of program execution. You can use 
the TYPE command to display source code from a module other than the one 
currently executing. In that case, you need to use a "path name" to specify 
the module. For example, the following command displays lines 16 through 
21 of module TEST: 

DBG> TYPE TEST\16:21 

Path names are discussed in more detail in the next section, in relation to the 
STEP command. 


1.2.4 Controlling and Monitoring Program Execution 

This section covers the following topics: 

• Starting and resuming program execution with the GO command 

• Stepping through the program's code with the STEP command 

• Determining the current location of the program counter (PC) with the 
SHOW CALLS command 

• Suspending program execution with breakpoints 

• Tracing program execution with tracepoints 

• Monitoring changes in variables with watchpoints 

With this information you will be able to pick program locations where you 
can test and manipulate the contents of variables as described in Section 1.2.5. 


1.2.4.1 Starting and Resuming Program Execution 

There are two commands for starting or resuming program execution—GO 
and STEP. GO simply starts execution. STEP (discussed in the next section) 
lets you execute a specified number of source lines or instructions. You use 
one or the other command according to the circumstances. 

One possible use of the GO command is immediately after you invoke 
the debugger. With most programming languages, execution is suspended 
directly at the start of the main program. For example (the main program is 
INVENTORY in this case): 

$ RUN INVENTORY 

VAX DEBUG Version 4.4 

%DEBUG-I-INITIAL, language is COBOL, module set to ’INVENTORY’ 

DBG> 


1-9 













Introduction to the VAX/VMS Debugger 


In some cases, however, the debugger suspends execution before the start of 
the main program, so that you can choose to execute some initialization code 
under debugger control. This occurs, for example, with all Ada programs 
and with FORTRAN programs compiled with the /CHECK=UNDERFLOW 
qualifier. The debugger indicates these cases with a "NOTATMAIN" message. 
For example: 

$ RUN HOTEL 


VAX DEBUG Version 4.4 

‘/.DEBUG-1-INITIAL, language is ADA. module set to ’HOTEL’ 

•/.DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 

Typing GO will then get you to the start of the main program. 

You will probably use the GO command most often in conjunction with 
breakpoints, tracepoints, and watchpoints (described later in this section). If 
you set a breakpoint in the path of execution and then type GO, execution 
will be suspended at that breakpoint. Similarly, if you set a tracepoint, 
execution will be monitored as it passes through that tracepoint. And if 
you set a watchpoint, execution will be suspended when the value of the 
"watched" variable changes. 

The GO command is also useful if you want to test for an exception condition 
or an infinite loop. If an exception condition that is not handled by your 
program occurs, the debugger will take over and display the DBG> prompt 
so that you can issue commands. If you are using screen mode, the pointer in 
the source display will indicate where execution stopped. The SHOW CALLS 
command (also explained later in this section) is useful at this point because 
it identifies the currently active routine calls (the call stack). 

In the case of an infinite loop, the program will not terminate, so the debugger 
prompt will not reappear. To obtain the prompt, interrupt the program with 
CTRL/Y and then issue the DCL DEBUG command. You can then look at 
the source display and a SHOW CALLS display to locate the PC. 


1.2.4.2 Stepping Through the Program's Code 

The STEP command is useful when you want to execute a specified number 
of source lines or instructions, or if you want to execute the program to the 
next instruction of a particular kind, for example to the next CALL instruction. 

By default, the STEP command executes a single source line at a time. In the 
following example, the STEP command executes one line, reports the action 
("stepped to . . . "), and displays the line number (27) and source code of the 
next line to be executed: 

DBG> STEP 

stepped to TEST\COUNT\*/.LINE 27 
27: X := X + 1; 

DBG> 

The PC is now at the first machine code instruction for line 27 of module 
TEST; line 27 is in COUNT, a routine within module TEST. 

When displaying a program symbol (for example, a line number, routine 
name, or variable name), the debugger always uses a path name. A path 
name consists of the symbol plus a prefix that identifies the symbol's location. 
In the preceding example, the path name is TEST\COUNT\%LINE 27. The 
leftmost element of a path name is the module name. Moving toward the 
right, the path name lists any successively nested routines and blocks that 
enclose the symbol. A backslash character (\) is used to separate elements 
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(except when the language is Ada, where a period is used, to parallel Ada 
syntax). 

A path name uniquely identifies a symbol of your program to the debugger. 
But in general, you need to use path names in commands only if the debugger 
tells you that a symbol you have specified is not unique (see Section 1.2.6.2). 
(Usually the debugger can figure out the symbol you mean from its context). 

Let us now return to the STEP command. You can specify a number of 
lines for the STEP command to execute. In the following example, the STEP 
command executes three lines: 

DBG> STEP 3 

Note that only those source lines for which code instructions were generated 
by the compiler are recognized as executable lines by the debugger. The 
debugger skips over any other lines—for example, comment lines. 

You can specify different stepping modes, such as stepping by instruction 
rather than by line (SET STEP INSTRUCTION). Also, by default, the 
debugger steps "over" called routines—execution is not suspended within 
a called routine, although the routine is executed. By issuing the SET STEP 
INTO command, you tell the debugger to suspend execution within called 
routines as well as within the currently executing module. (SET STEP OVER 
is the default mode). 


1.2.4.3 Determining the Current Location of the Program Counter 

The SHOW CALLS command is useful when you are unsure about the 
current location of the PC (for example, after returning to the debugger 
following a CTRL/Y interrupt). The command shows a traceback that lists 
the sequence of calls leading to the currently executing routine. For example: 

DBG> SHOW CALLS 


module name 

routine name 

line 

rel PC 

abs PC 

♦TEST 

PRODUCT 

18 

00000009 

0000063C 

♦TEST 

COUNT 

47 

00000009 

00000647 

♦MY.PROG 

MY.PROG 

21 

0000000D 

00000653 


DBG> 

For each routine (beginning with the currently executing routine), the 
debugger displays the following information: the name of the module that 
contains the routine, the name of the routine, the line number at which the 
call was made (or at which execution is suspended, in the case of the current 
routine), and the corresponding PC addresses (the relative PC address from 
the start of the routine, and the absolute PC address of the program). This 
example indicates that execution is currently at line 18 of routine PRODUCT 
(in module TEST), which was called from line 47 of routine COUNT (in 
module TEST), which was called from line 21 of routine MY_PROG (in 
module MY_PROG). 
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1.2.4.4 Suspending Program Execution 

The SET BREAK command lets you select locations for program suspension 
(breakpoints), where you can issue commands to check the call stack, examine 
the current values of variables, and so on. 

A typical use of the SET BREAK command is illustrated in the following 
example: 

DBG> SET BREAK COUNT 
DBG> GO 


break at PR0G2\C0UNT 

54: procedure COUNT(X,Y:INTEGER); 

DBG> 

In the example, the SET BREAK command sets a breakpoint on routine 
COUNT (at the start of the routine's code); the GO command starts execution; 
when routine COUNT is encountered, execution is suspended, the debugger 
announces that the breakpoint at COUNT has been reached ("break at . . . "), 
displays the source line (54) where execution is suspended, and prompts 
for another command. At this breakpoint, you could STEP through routine 
COUNT and then use the EXAMINE command (discussed further on) to 
check on the values of X and Y. 

When using the SET BREAK command, you can specify program locations 
using various kinds of address expressions (for example, line numbers, routine 
names, instructions, virtual memory addresses, byte offsets). With high level 
languages, you typically use routine names, labels, or line numbers, possibly 
with path names to ensure uniqueness. 

Routine names and labels should be specified as they appear in the source 
code. Line numbers may be derived from either a source code display or a 
listing file. When specifying a line number, use the prefix %LINE. Otherwise 
the debugger will interpret the line number as a memory location. For 
example, the next command sets a breakpoint at line 41 of the currently 
executing module: the debugger will suspend execution when the PC is at 
the start of line 41. 

DBG> SET BREAK ‘/.LINE 41 

Note that you can set breakpoints only on lines that resulted in machine code 
instructions. The debugger warns you if you try to do otherwise (for example 
on a comment line). If you want to pick a line number in a module other 
than the one currently executing, you need to specify the module's name in a 
path name. For example: 

DBG> SET BREAK SCREEN.IOV/.LINE 58 

You do not always have to specify a particular program location, such as 
line 58 or COUNT, to set a breakpoint. You can also use the SET BREAK 
command with a qualifier, but no parameter, to break on every line, or on 
every CALL instruction, and so on. For example: 

DBG> SET BREAK/LINE 
DBG> SET BREAK/CALL 

Also, you can set breakpoints on events , such as exceptions, or state 
transitions in Ada tasking programs. 
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You can conditionalize a breakpoint (with a "WHEN" clause) or specify that 
a list of commands be executed at the breakpoint (with a "DO" clause). For 
example, the next command sets a breakpoint on the label LOOP3. The 
debugger DO clause displays the value of the variable TEMP whenever the 
breakpoint is triggered. 

DBG> SET BREAK L00P3 DO (EXAMINE TEMP) 

DBG> GO 


break at C0UNTER\L00P3 

37: L00P3: FOR I = 1 TO 10 DO 

COUNTER\TEMP: 284.19 

DBG> 

To display the currently active breakpoints, type SHOW BREAK: 

DBG> SHOW BREAK 

breakpoint at SCREEN.IOY/.LINE 58 
breakpoint at PR0G2\L00P3 
do (EXAMINE TEMP) 


DBG> 

To cancel a breakpoint, type CANCEL BREAK, specifying the program 
location exactly as you did when setting the breakpoint. CANCEL BREAK 
/ALL cancels all breakpoints. 


1.2.4.5 Tracing Program Execution 

The SET TRACE command lets you select locations for tracing the execution 
of your program (tracepoints), without stopping its execution. After setting a 
tracepoint, you can start execution with the GO command and then monitor 
the PC's path, checking for unexpected behavior. By setting a tracepoint on a 
routine, you can also monitor the number of times it is called. 

As with breakpoints, every time a tracepoint is reached, the debugger issues 
a message and displays the source line. But the program continues executing, 
and the debugger prompt is not displayed. For example: 

DBG> SET TRACE COUNT 
DBG> GO 


trace at PR0G2\C0UNT 

54: procedure C0UNT(X,Y:INTEGER); 


This is the only difference between a breakpoint and a tracepoint. When 
using the SET TRACE command, you specify address expressions, qualifiers, 
and optional clauses exactly as with the SET BREAK command. 

The /LINE qualifier causes the SET TRACE command to trace every line and 
is a convenient means of checking the execution path. By default, lines are 
traced within all called routines as well as the currently executing routine. If 
you do not want to trace system routines or routines in shareable images, use 
the /NOSYSTEM or /NOSHARE qualifiers. For example: 

DBG> SET TRACE/LINE/NOSYSTEM/NOSHARE 
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The /SILENT qualifier suppresses the trace message and source code display. 
This is useful when you want to use the SET TRACE command simply to 
execute a debugger command at the tracepoint. For example: 

DBG> SET TRACE/SILENT ‘/.LINE 83 DO (EXAMINE STATUS) 

DBG> GO 


SCREEN_IO\CLEAR\STATUS: OFF 


1.2.4.6 Monitoring Changes in Variables 

The SET WATCH command lets you specify program variables that the 
debugger will monitor as your program executes. This process is called 
setting watchpoints. If the program modifies the value of a "watched" 
variable, the debugger suspends execution and displays information. The 
debugger monitors watchpoints continuously during program execution. 
(Note that the SET WATCH command may also be used to monitor arbitrary 
program locations, not just variables). 

To set a watchpoint on a variable, specify the variable's name with the SET 
WATCH command. For example, the following command sets a watchpoint 
on the variable TOTAL: 

DBG> SET WATCH TOTAL 

Subsequently, every time the program modifies the value of TOTAL, the 
watchpoint is triggered. 

The next example shows what happens when your program modifies the 
contents of a watched variable. 

DBG> SET WATCH TOTAL 
DBG> GO 


watch of SCREEN_IO\TOTALV/.LINE 13 
13: TOTAL := TOTAL + 1; 

old value: 16 
new value: 17 

break at SCREEN.IO.‘/.LINE 14 
14: POP(TOTAL); 

DBG> 

In this example, a watchpoint is set on the variable TOTAL and execution 
is started. When the value of TOTAL changes, execution is suspended. The 
debugger announces the event ("watch of . . . "), identifying where TOTAL 
changed (the start of line 13) and the associated source line. The debugger 
then displays the old and new values and announces that execution has been 
suspended at the start of the next line (14). Finally, the debugger prompts for 
another command. Note that when a change in a variable occurs at a point 
other than the start of a source line, the debugger gives the line number plus 
the byte offset from the start of the line. 


1.2.5 Examining and Manipulating Data 

This section explains how to use the EXAMINE, DEPOSIT, and EVALUATE 
commands to display and modify the contents of variables and evaluate 
expressions. 
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1.2.5.1 Displaying the Values of Variables 

To display the value of a variable, use the EXAMINE command as follows: 


EXAMINE variable-name 

The debugger recognizes the compiler-generated data type of the variable 
you specify and retrieves and formats the data accordingly. The following 
examples illustrate how to use the EXAMINE command. 

Examine a string variable: 

dbg> examine employee.name 

PAYROLL\EMPLOYEE_NAME: "Peter C. Lombardi" 

DBG> 

Examine three integer variables: 
dbg> examine width, length, area 

SIZEXWIDTH: 4 

SIZE\LENGTH: 7 
SIZE\AREA: 28 

DBG> 

Examine a two-dimensional array of real numbers (three per dimension): 
dbg> examine real.array 

PR0G2\REAL_ARRAY 

(1.1) : 27.01000 

(1.2) : 31.00000 

(1.3) : 12.48000 

(2.1) : 15.08000 

(2.2) : 22.30000 

(2.3) : 18.73000 

DBG> 

Examine element 4 of a one-dimensional array of characters: 
dbg> examine char.array(4) 

PR0G2\CHAR_ARRAY(4): ’m’ 

DBG> 

Examine a record variable (COBOL example): 
dbg> examine part 

INVENTORY\PART: 

ITEM: "WF-1247" 

PRICE: 49.95 

IN-STOCK: 24 

DBG> 

Examine a record component (COBOL example): 
dbg> examine in-stock of part 

INVENTORY\IN-STOCK of PART: 

IN-STOCK: 24 

DBG> 

Note that the EXAMINE command may be used with any kind of address 
expression (not just a variable name) to display the contents of a program 
location. The debugger associates certain default data types with untyped 
locations. You can override the defaults for typed and untyped locations if 
you want the data to be interpreted and displayed in some other data format. 
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1.2.5.2 Changing the Values of Variables 

To change the value of a variable, use the DEPOSIT command as follows: 

DEPOSIT variable-name = value 

The DEPOSIT command is like an assignment statement in most 
programming languages. 

In the following examples, the DEPOSIT command assigns new values to 
different variables. The debugger checks that the value assigned, which may 
be a language expression, is consistent with the data type and dimensional 
constraints of the variable. 

Deposit a string value (it must be enclosed in quote characters or 
apostrophes): 

DBG> DEPOSIT PART-NUMBER = "WG-7619.3-84" 

Deposit an integer expression: 

DBG> DEPOSIT WIDTH = CURRENT.WIDTH + 10 

Deposit element 12 of an array of characters (you cannot deposit an entire 
array aggregate with a single DEPOSIT command, only an element): 

DBG> DEPOSIT C_ARRAY(12) ’K’ 

Deposit a record component (you cannot deposit an entire record aggregate 
with a single DEPOSIT command, only a component): 

DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 

Deposit an out-of-bounds value (X was declared as a positive integer): 

DBG> DEPOSIT X * -14 

7.DEBUG-I-IVAL0UTBNDS, value assigned is out of bounds at or near ’DEPOSIT’ 

As with the EXAMINE command, you can specify any kind of address 
expression (not just a variable name) with the DEPOSIT command. You can 
override the defaults for typed and untyped locations if you want the data to 
be interpreted in some other data format. 

1.2.5.3 Evaluating Expressions 

To evaluate a language expression, use the EVALUATE command as follows: 

EVALUATE language-expression 

The debugger recognizes the operators and expression syntax of the currently 
set language. In the following example, the value 45 is assigned to the 
integer variable WIDTH; the EVALUATE command then obtains the sum of 
the current value of WIDTH and 7: 

DBG> DEPOSIT WIDTH := 45 
DBG> EVALUATE WIDTH + 7 
52 

DBG> 

In the next example, the values TRUE and FALSE are assigned to the boolean 
variables WILLING and ABLE, respectively; the EVALUATE command then 
obtains the logical conjunction of these values: 

DBG> DEPOSIT WILLING := TRUE 
DBG> DEPOSIT ABLE := FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 
DBG> 
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1.2.6 Controlling Symbol References 

In most cases, the manner in which the debugger handles the symbols 
(variable names, and so on) that you reference in debugger commands should 
be transparent to you. However, two areas deserve mention because they 
may require some intervention on your part: 

• Module setting 

• Multiply-defined symbols 


1.2.6.1 Module Setting 

To facilitate symbol searches, the debugger loads symbol records from the 
executable image into a run-time symbol table (RST), where they can be 
accessed efficiently. Unless a symbol record is in the RST, the debugger 
cannot recognize or properly interpret that symbol. 

Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of 
execution. The loading process is called module setting, because all of the 
symbol records of a given module are loaded into the RST at one time. 

At debugger start up, only the module containing the image transfer address 
is set. As your program executes, whenever the debugger interrupts execution 
it sets the module surrounding the current PC location. This lets you 
reference the symbols that should be visible at the current PC location. 

If you try to reference a symbol in a module that has not been set, the 
debugger will warn you that the symbol is not in the RST. For example: 

DBG> EXAMINE K 

7.DEBUG-W-NOSYMBOL, symbol ’K’ is not in symbol table 
DBG> 

You must then use the SET MODULE command to set the module containing 
that symbol manually: 

DBG> SET MODULE M0D3 
DBG> EXAMINE K 
M0D3\R0UT2\K: 26 
DBG> 

The SHOW MODULE command lists the modules of your program and 
identifies which modules are set. 

Note that dynamic module setting may slow the debugger down as more and 
more modules are set. If performance becomes a problem, you can use the 
CANCEL MODULE command to reduce the number of set modules, or you 
can disable dynamic module setting by issuing the SET MODE NODYNAMIC 
command (SET MODE DYNAMIC enables dynamic module setting). 
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1.2.6.2 Resolving Multiply-Defined Symbols 

The debugger finds the symbols that you reference in commands according 
to the scope and visibility rules of the currently set language. In general, the 
debugger first looks for a symbol within the block or routine surrounding 
the current PC location; if the symbol is not found in that scope region, the 
debugger searches the nesting program unit, then its nesting unit, and so on. 
(The precise manner depends on the currently set language and guarantees 
that the proper declaration of a multiply-defined symbol is selected.) 

The debugger must let you reference symbols throughout your program, 
not just those that are visible at the current PC location, to allow you to 
set breakpoints in arbitrary areas or examine arbitrary variables, and so 
on. Therefore, if the symbol is not visible at the current PC location, the 
debugger also searches other scope regions. First, it looks within the currently 
executing routine, then the caller of that routine, then its caller, and so on. 
Symbolically, this search list is denoted 0,2,2, . . . ,n, where n is the number 
of calls in the call stack. Within each of these scope regions, the debugger 
uses the visibility rules of the language to locate a symbol. If the symbol is 
not found, the debugger then searches the rest of the run-time symbol table. 

If the debugger cannot resolve a multiply-defined symbol, it issues a message. 
For example: 

DBG> EXAMINE Y 

‘/.DEBUG-W-NOUNIQUE, symbol »Y* is not unique 
DBG> 

In that case, you can use a path-name prefix to uniquely specify a declaration 
of the given symbol. First, use the SHOW SYMBOL command to identify 
all path names associated with the given symbol; then use the desired path 
name when referencing the symbol. For example: 

DBG> SHOW SYMBOL Y 

data M0D7\R0UT3\BL0CK1\Y 

data M0D4\R0UT2\Y 

DBG> EXAMINE M0D4\R0UT2\Y 

M0D4\R0UT2\Y: 12 

DBG> 

If you need to refer to a particular declaration of Y repeatedly, use the SET 
SCOPE command to establish a new default scope for symbol lookup. Then, 
references to Y without a path-name prefix will specify the declaration of Y 
that is visible in the new scope region. For example: 

DBG> SET SCOPE M0D4\R0UT2 
DBG> EXAMINE Y 
M0D4\R0UT2\Y: 12 
DBG> 

To display the current scope for symbol lookup, use the SHOW SCOPE 
command. To restore the default scope, use the CANCEL SCOPE command. 
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1.2.7 A Sample Debugging Session 

This section goes through a debugging session with a simple FORTRAN 
program that contains a logic error: 

1: INTEGER INARR(20), 0UTARR(20) 

2: C 

3: C -Read the input array from the data file. 

4: OPEN(UNIT=8, FILE=’DATAFILE.DAT’, STATUS= * OLD *) 

5: READ(8,*) N. (INARR(I), 1=1,N) 

6: C 

7: C -Square all non-zero elements and store in OUTARR. 

8: K = 0 

9: DO 10 I = 1, N 

10: IF(INARRU) .NE. 0) THEN 

11: OUTARR(K) = INARR(I)**2 

12: ENDIF 

13: 10 CONTINUE 

14: C 

15: C -Print the squared output values. Then stop. 

16: PRINT 20. K 

17: 20 FORMAT(* Number of non-zero elements is’,14) 

18: DO 40 I = 1, K 

19: PRINT 30, I, OUTARR(I) 

20: 30 FORMAT(’ Element*,14,’ has value’,16) 

21: 40 CONTINUE 

22: END 

As you read on, you can refer back to this code to identify source lines. The 
program reads a sequence of integer numbers from a data file (lines 4 and 5) 
and saves these numbers in the array INARR. The program then enters a loop 
(lines 8 through 13) where it copies the square of each nonzero integer into 
another array OUTARR. Finally, it prints the number of nonzero elements in 
the original sequence and the square of each such element (lines 16 through 
21 ). 

The error in the program occurs when variable K, which keeps track of the 
current index into OUTARR, is not incremented in the loop on lines 9 through 
13. The statement K = K + 1 should be inserted just before line 11. 

To find this error, first compile, link, and run the program: 

$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES 
$ LINK/DEBUG SQUARES 
$ RUN SQUARES 

VAX DEBUG Version 4.4 


'/.DEBUG-1-INITIAL, language is FORTRAN, module set to ’ SQUARES$MAIN ’ 

DBG> 

You can now enter debugger commands. To step forward 4 lines, enter this 
command: 

DBG> STEP 4 

stepped to SQUARES$MAIN\'/.LINE 9 
DBG> 

To check the current values of variables N and K, enter this command: 

DBG> EXAM N, K 
SQUARES$MAIN\N: 9 

SQUARES$MAIN\K: 0 

DBG> 
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The values of N and K are both correct at this point in the execution. Now 
enter the command STEP 2 to enter the loop that copies and squares all 
nonzero elements of INARR into OUTARR. 

DBG> STEP 2 

stepped to SQUARES$MAIN\*/.LINE 11 
DBG> 

To see if I and K have the expected values, enter EXAM I, K. 

DBG> EXAM I,K 
SQUARES$MAIN\I: 1 

SQUARES$MAIN\K: 0 

DBG> 

I has the expected value (namely 1), but K has the value zero, which is not 
the expected value. Now you can see the error in the program: K should 
be incremented in the loop just before it is used in line 11. To check this 
hypothesis, "repair" the program with the following debugger commands: 

DBG> DEPOSIT K * 1 

DBG> SET TRACE/SILENT ‘/.LINE 11 DO (DEPOSIT K = K + 1) 

DBG> 

The first command gives K the value it should have now, namely 1. The 
second command specifies that the debugger should perform the debugger 
command DEPOSIT K = K + 1 each time line 11 is reached in the execution. 
The /SILENT qualifier suppresses the "trace at" message that would otherwise 
be announced each time line 11 is executed. The net effect is that the program 
has been "patched" to perform correctly by the SET TRACE command. 

Line 22 is a suitable location for a breakpoint that will stop program execution 
after testing the correctness of your "patch." Set a breakpoint as follows: 

DBG> SET BREAK '/.LINE 22 
DBG> 

You now want to run your program to test your patch. Enter GO to execute 
the program until it hits the breakpoint at line 22. 

DBG> GO 

Number of non-zero elements is 6 


Element 

1 

has 

value 

16 

Element 

2 

has 

value 

36 

Element 

3 

has 

value 

9 

Element 

4 

has 

value 

49 

Element 

5 

has 

value 

81 

Element 

6 

has 

value 

1 


break at SQUARES$MAIN\7,LINE 22 
22: END 

DBG> 

The program output shows that the program seems to work properly with the 
DEPOSIT K = K + 1 patch. You can now use the EDIT command to invoke 
the VAX Language Sensitive Editor, or another editor previously established 
with the SET EDITOR command: 

DBG> EDIT 

The editor positions the cursor at the same line that is marked by the pointer 
in the debugger's source display. 
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The corrected portion of the source code follows. 


8: K = 0 

9: DO 10 I = 1. N 

10: IF(INARR(I) .NE. 0) THEN 

11: K = K + 1 

12: OUTARR(K) = INARR(I)**2 

13: ENDIF 

14: 10 CONTINUE 


Now you can compile, link, and run the program again under debugger 
control, to check that it behaves correctly: 

$ FORTRAN/DEBUG/NOPTIMIZE SQUARES 
$ LINK/DEBUG SQUARES 
$ RUN SQUARES 

To set a breakpoint at line 12 where the values of I and K will be displayed 
automatically, enter this command (the subsequent GO command starts 
execution): 

DBG> SET BREAK ’/.LINE 12 DO (EXAMINE I,K) 

DBG> GO 


SQUARES$MAIN\I: 1 
SQUARES$MAIN\K: 1 
DBG> GO 

SQUARES$MAIN\I: 2 
SQUARES$MAIN\K: 2 
DBG> GO 

SQUARES$MAIN\I: 4 
SQUARES$MAIN\K: 3 


At the first breakpoint, the value of K is 1, indicating that the program is 
behaving correctly so far. Each additional GO command will show the 
current values of I and K. After two GO commands, K is now 3, as expected, 
but note that I is 4. This indicates that one of the INARR elements was 
zero so that lines 11 and 12 were not executed (and K not incremented) on 
one iteration of the DO loop. This confirms that the program is behaving 
correctly. 


1.3 Debugger Command Summary 

The following sections list all of the debugger commands and any related 
DCL commands in functional groupings, along with brief descriptions. 


1—21 











Introduction to the VAX/VMS Debugger 


1.3.1 Starting and Terminating a Debugging Session 


($) RUN 1 

($) RUN/INOJDEBUG 1 

EXIT, CTRL/Z 
QUIT 

CTRL/Y 

CTRL/C 

($) CONTINUE 1 
($) DEBUG 1 
ATTACH 
SPAWN 


Invokes the debugger if LINK/DEBUG was used 

Controls whether the debugger is invoked when the 
program is executed 

Ends a debugging session, executing all exit handlers 

Ends a debugging session without executing any exit 
handlers declared in the program 

Interrupts a debugging session, returning you to DCL 
level 

Like CTRL/Y, unless the program has a CTRL/C 
service routine 

Resumes a debugging session after CTRL/Y 
interruption 

Resumes a debugging session after CTRL/Y 
interruption but returns you to the debugger prompt 

Passes control of your terminal from the current 
process to another process (like $ ATTACH) 

Creates a subprocess. Lets you issue DCL commands 
without interrupting your debugging context (like $ 
SPAWN) 


^his is a DCL command, not a debugger command. 


1.3.2 Controlling and Monitoring Program Execution 


GO 

STEP 

(SET,SHOW) STEP 

(SET,SHOW,CANCEL) BREAK 
(SET,SHOW,CANCEL) TRACE 
(SET,SHOW,CANCEL) WATCH 
(SET,CANCEL) EXCEPTION BREAK 
SHOW CALLS 


Starts or resumes program execution 

Executes the program up to the next 
line, instruction, or specified instruction 

(Establishes, displays) the default 
qualifiers for the STEP command 

(Sets, displays, cancels) breakpoints 
(Sets, displays, cancels) tracepoints 
(Sets, displays, cancels) watchpoints 
(Sets, cancels) exception breakpoints 

Identifies the currently active routine 
calls 
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SHOW STACK 
CALL 


Gives additional information about the 
currently active routine calls 

Calls a routine 


1.3.3 Examining and Manipulating Data 


EXAMINE Displays the value of a variable or the contents of a program 
location 

DEPOSIT Changes the value of a variable or the contents of a program 
location 


EVALUATE Evaluates a language or address expression 


1.3.4 Controlling Type Selection and Symbolization 


(SET,SHOW,CANCEL) RADIX 
(SET,SHOW,CANCEL) TYPE 
SET MODE [NO]G_FLOAT 


(Establishes, displays, restores) the radix for data 
entry and display 

(Establishes, displays, restores) the type to be 
associated with untyped program locations 

Controls whether double-precision floating-point 
constants are interpreted as G—FLOAT or D_ 
FLOAT 


SET MODE [NOJLINE Controls whether code locations are displayed 

in terms of line numbers or routine-name + byte 
offset 


SET MODE [NOJSYMBOLIC 
SYMBOLIZE 


Controls whether code locations are displayed 
symbolically or in terms of numeric addresses 

Converts a virtual address to a symbolic address 


1.3.5 Controlling Symbol Lookup 


SHOW SYMBOL 

(SET,SHOW,CANCEL) MODULE 

(SET,SHOW,CANCEL) IMAGE 

SET MODE [NO]DYNAMIC 

ALLOCATE 

(SET,SHOW,CANCEL) SCOPE 


Displays symbols in your program 

"Sets" a module by loading its symbol 
records into the debugger's symbol table, 
identifies, cancels a "set" module 

"Sets" a shareable image by loading data 
structures into the debugger's symbol table, 
identifies, cancels a "set" image 

Controls whether or not modules are "set" 
automatically when the debugger interrupts 
execution 

Expands the debugger's memory pool to let 
you "set" more modules 

(Establishes, displays, restores) the scope for 
symbol lookup 
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1.3.6 Displaying Source Code 

TYPE 

EXAMINE/SOURCE 
(SET,SHOW,CANCEL) SOURCE 
SEARCH 

(SET,SHOW) SEARCH 

(SET,SHOW) MAX _SOURCE_ 
FILES 

(SET,SHOW) MARGINS 


Displays lines of source code 

Displays the source code at the location 
specified by the address expression 

(Creates, displays, cancels) a source 
directory search list 

Searches the source code for the specified 
string 

(Establishes, displays) the default qualifiers 
for the SEARCH command 

(Establishes, displays) the maximum number 
of source files that may be kept open at 
one time 

(Establishes, displays) the left and right 
margin settings for displaying source code 


1.3.7 Screen Mode 


SET MODE [NOJSCREEN 
SET MODE [NOJSCROLL 

DISPLAY 

(SET,SHOW,CANCEL) DISPLAY 

(SET,SHOW,CANCEL) 

WINDOW 

SELECT 
SHOW SELECT 

SCROLL 

SAVE 

EXTRACT 


Enables/disables screen mode 

Controls whether an output display is updated 
line by line or once per command 

Modifies an existing display 
(Creates, identifies, deletes) a display 

(Creates, identifies, deletes) a window 
definition 

Selects a display for a display attribute 

Identifies the displays selected for each of the 
display attributes 

Scrolls a display 

Saves the current contents of a display into 
another display 

Saves a display or the current screen state 
into a file 


EXPAND 

MOVE 

(SET,SHOW) TERMINAL 
CTRL/W,DISPLAY/REFRESH 


Expands or contracts a display 
Moves a display across the screen 

(Establishes, displays) the height and width of 
the screen 

Refreshes the screen 


1.3.8 Source Editing 


EDIT 

(SET,SHOW) EDITOR 
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1.3.9 Defining Symbols 

Defines a symbol as an address, command, or value 
Deletes symbol definitions 

(Establishes, displays) the default qualifier for the 
DEFINE command 

Identifies symbols that have been defined 


DEFINE 

DELETE (UNDEFINE) 

(SET,SHOW) DEFINE 

SHOW SYMBOL/DEFINED 


1.3.10 Keypad Mode 


SET MODE [NO]KEYPAD 
DEFINE/KEY 

DELETE/KEY (UNDEFINE/KEY) 
SET KEY 
SHOW KEY 


Enables/disables keypad mode 
Creates key definitions 
Deletes key definitions 
Establishes the key definition state 
Displays key definitions 


1.3.11 Command Procedures and Log Files 


DECLARE 

(SET,SHOW) LOG 
SET OUTPUT [NO]LOG 

SET OUTPUT [NO]SCREEN_LOG 

SET OUTPUT [NO]VERIFY 

SHOW OUTPUT 
(SET,SHOW) ATSIGN 

@file-spec 


Defines parameters to be passed to 
command procedures 

(Specifies, identifies) the debugger log file 

Controls whether a debugging session is 
logged 

Controls whether, in screen mode, the 
screen contents are logged as the screen is 
updated 

Controls whether debugger commands 
are displayed as a command procedure is 
executed 

Displays the current output options 
established by the SET OUTPUT command 

(Establishes, displays) the default file 
specification that the debugger uses to 
search for command procedures 

Executes a command procedure 


1.3.12 Control Structures 

Executes a list of commands conditionally 
Executes a list of commands repetitively 
Executes a list of commands repetitively 


IF 

FOR 

REPEAT 
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WHILE Executes a list of commands conditionally 

EXITLOOP Exits an enclosing WHILE, REPEAT, or FOR loop 


1.3.13 Debugging Special Cases 


SET OUTPUT [NO]TERMINAL 

(SET,SHOW) LANGUAGE 
(SET,SHOW) EVENT_FACILITY 

SHOW EXIT_HANDLERS 

(SET,SHOW) TASK 

(DISABLE,ENABLE,SHOW) AST 


Controls whether debugger output, except 
for diagnostic messages, is displayed or 
suppressed 

(Establishes, displays) the current language 

(Establishes, identifies) the current run-time 
facility for language-specific events 

Identifies the exit handlers declared in the 
program 

Modifies the tasking environment, displays 
task information 

(Disables, enables) the delivery of ASTs in the 
program, identifies whether delivery is enabled 
or disabled 
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2 Controlling the Debugging Environment 


The following subjects are discussed in this chapter: 

• Controlling what symbolic information is available to you during a 
debugging session. 

• Options for running your program. 

• Debugger activation. 

• Debugger initialization files. 

• Language-dependent and -independent parameters. 

• Log files. 

• Command procedures. 

• Interrupting a debugging session. 


2.1 Controlling Symbol Information 

When you run your program under debugger control, you can debug your 
program symbolically, using the symbols you used in your source program. 

Symbolic debugging is possible because the debugger uses a symbol table 
which it stores in the executable image file (EXE) that you run. Part of the 
symbol table—the debugger symbol table (DST)—is created by the compiler 
or the assembler. Another part—the global symbol table (GST)—is created 
by the linker. When you specify the /DEBUG command qualifier on both the 
compile and the LINK commands, you are controlling the creation of these 
symbol tables. 

In general, if you intend to debug your program, you should both compile 
and link your program using the /DEBUG command qualifier. The symbol 
table information generated by the compiler is processed by the linker, so you 
can obtain the full range of symbol table information at run time. 

The example below shows how to start a debugging session during which 
you can use all the symbolic information in the program MEANSUB. 

$ BASIC/DEBUG MEANSUB 
$ LINK/DEBUG MEANSUB 
$ RUN MEANSUB 

VAX-ii DEBUG Version ***** 

•/.DEBUG-1-INITIAL, language is BASIC, module set to ’MEANSUB$MAIN* 

DBG> 

Note that you do not have to specify RUN/DEBUG if you specify LINK 
/DEBUG. If, however, you specified the /DEBUG command qualifier when 
you linked your program but you want your program to run without debugger 
control, you can specify the /NODEBUG command qualifier at run time. 

Once you have debugged your program, you may want to recompile and 
relink it without creating symbol table information. In this way, you can 
reduce the size of both your object (OBJ) and image (EXE) files. 
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2.1.1 Compiling with the /DEBUG and the /TRACE Command Qualifiers 

You can specify the /DEBUG command qualifier on a compile command, the 
LINK command, and the RUN command. 

When you specify the /DEBUG qualifier on a compile command, the compiler 
then creates a symbol table (the DST) containing information both about the 
names you used in your program as well as about line numbers. For this 
reason, you should always use the /DEBUG qualifier when you compile any 
program that you intend to debug. 

If you do not specify the /DEBUG command qualifier on the compile 
command, information about names of local variables are not included in 
the symbol table. However, the compiler still includes information about 
routine names and line numbers so it can give a symbolic traceback if your 
program terminates with a severe error. 

If you do not want any symbol table (including the traceback information) 
to be created, you can specify the /DEBUG=NONE qualifier on the compiler 
command. For language-specific details, refer to the user's guide for the 
language you are using. 


2.1.2 Linking with the /DEBUG and the /TRACE Command Qualifiers 

When you specify the /DEBUG command qualifier with the LINK command, 
the linker creates a global symbol table (the GST) with the names of all 
your global data. The linker includes all the symbol tables that have been 
generated by the compiler. In addition, the linker sets a flag in the image 
file which causes your program to run under debugger control when it is 
executed. 

If you do not specify the /DEBUG qualifier with the LINK command, then 
the linker includes only the symbol table information that is necessary for a 
symbolic traceback. The linker also does not set the flag in the image file that 
indicates debugger control. 

You can direct the linker to generate no symbol tables (including the traceback 
information) by specifying the /NOTRACE qualifier with the LINK command. 
As a result, you cannot debug your program using the debugger. 


2.2 Options for Running Your Program 

Use of the DCL commands RUN/[NO]DEBUG and DEBUG are explained in 
this section. 


2.2.1 Using the RUN/[NO]DEBUG Command 

You can use the /DEBUG and /NODEBUG command qualifiers on the RUN 
command to control whether your program runs under debugger control. 

If you did not specify the /DEBUG qualifier when you linked your program, 
then you must specify RUN/DEBUG if you want the debugger to receive 
control. In this case, however, you cannot debug your program using local 
symbols. 
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If you linked your program with the /DEBUG command qualifier, you can 
specify the /NODEBUG qualifier if you do not want your program to run 
under debugger control. 

Table 2-1 summarizes what symbolic information is available in the 
executable image when you specify the /DEBUG command qualifier with 
the compiler command, the LINK command, and the RUN command. 

Table 2-1 The /DEBUG Qualifier and Symbolic Debugging 


Compile (or Assembly) 
Command Qualifier 

LINK Command 
Qualifier 

RUN Command 
Qualifier 

Symbolic 

Information 

None 

None 

/DEBUG 

Traceback 

/DEBUG 

or 

/DEBUG=ALL 

None 

/DEBUG 

Traceback 

/NODEBUG 

or 

/DEBUG=NONE 

None 

/DEBUG 

None 

/DEBUG=TRACEBACK 

or 

=(TRACEBACK,NOSYMBOLS) 

None 

/DEBUG 

Traceback 

None 

/DEBUG 

None 

Traceback 
global symbols 

/DEBUG 

or 

/DEBUG=ALL 

/DEBUG 

None 

Local symbols 
global symbols 
traceback 

/NODEBUG 

or 

/DEBUG=NONE 

/DEBUG 

None 

Global symbols 

/DEBUG=TRACEBACK 

or 

=(TRACEBACK,NOSYMBOLS) 

/DEBUG 

None 

Traceback 
global symbols 


2.2.2 Using the DEBUG Command 

If your program is running without debugger control and you want to invoke 
the debugger, you must 

1 Interrupt the running program by entering CTRL/Y 

2 Issue the DEBUG command 

After you enter the DEBUG command, the debugger displays an 
informational message and the DBG> prompt, indicating that it is ready 
to accept a debugger command. 

To use this feature, you must, as a minimum, have linked your program with 
the /TRACE qualifier. To reference your program's symbols, you must have 
linked with the /DEBUG qualifier. Note that, under these conditions, you 
must then use the DCL command RUN/NODEBUG to execute the program 
without the debugger. 
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You will find the DEBUG command particularly useful when 

• Your program is in an infinite loop. After interrupting your program and 
entering the DEBUG command, you can debug your program to find the 
cause of the infinite loop. 

• You have entered the RUN/NODEBUG command but later decide that 
you want debugger control. 

• You have not specified the /DEBUG command qualifier at compile time, 
link time, or run time but want to debug your running program. Note 
that in this situation, most symbolic information is unavailable to the 
debugger; you must use virtual memory addresses and not symbols to 
refer to program and data locations. 

After you interrupt your running program and enter the DEBUG command, 
you will not know at which instruction your program was interrupted. To 
find out, issue the SHOW CALLS command. 

Note that you may enter certain DCL commands after you interrupt your 
program and still be able to start the debugger by subsequently entering the 
DEBUG command. See Section 2.7.2 for more information. 

The following example demonstrates how to interrupt your program and start 
the debugger using the DEBUG command. Note that CTRL/Y is echoed as 
"Interrupt" in reverse video. 

$ RUN PROG 


1 CTRL/Y I 

Interrupt 
$ DEBUG 

VAX-11 DEBUG Version ***** 

‘/.DEBUG-1-INITIAL, language is COBOL, module set to ’INVENTORY’ 
DBG> 


2.3 Debugger Activation 

The debugger is a shareable image that the VAX/VMS operating system 
maps into the address space of a user process when SYS$IMGSTA is the 
first entry in the transfer address array. SYS$IMGSTA is the first entry when 
you specify any one of the following combinations of DCL commands in the 
process of program development: 

• LINK/DEBUG and not RUN/NODEBUG 

• RUN/DEBUG (unless LINK/NOTRACEBACK) 

• DEBUG following program interruption (unless LINK/NOTRACEBACK) 

When the /NOTRACEBACK qualifier is specified at link time, the linker does 
not generate a debug symbol table (DST). Since a DST must be available at 
run time in order for the debugger to execute, specifying /NOTRACEBACK 
at link time inhibits the debugging of that image regardless of what other 
qualifiers are or are not specified at link or run time. 
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At run time, then, given any of the previously mentioned combinations of 
DCL commands, SYS$IMGSTA, a VAX/VMS component maps the debugger 
(that is, the shareable image DEBUG.EXE) into the highest-addressed portion 
of PO space adjacent to the user image and passes control to the debugger. 

When the debugger receives control, it initializes a portion of the address 
space adjacent to the debugger image with three symbol tables—the DST, 
the GST, and the RST. See Sections 4.2.1, 4.2.2, and 4.2.3 for a description of 
these symbol tables and how the debugger uses them. 

Figure 2-1 depicts the layout of the virtual address space of a process that is 
running a program under debugger control. 

Figure 2-1 Process Address Space Layout 
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USER PROGRAM 
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DEBUGGER CODE 
(DEBUG.EXE) 


DEBUG SYMBOL TABLE 
(DST) 


GLOBAL SYMBOL TABLE 
(GST) 


RUN TIME SYMBOL TABLE 
(RST) 
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2.4 Debugger Initialization Files 

Debugger initialization files contain commands you always issue after you 
enter the debugger. Then, every time you invoke the debugger, those 
commands are automatically executed. 

For example, you might have a file DEBUG.INI containing the following 
commands: 

SET SOURCE DISK$ 

SET STEP LINE, SOURCE 
SET MODULE/ALL 
SET OUTPUT LOG.VER 
SET LOG LINK.LOG 

DEFINE/COMMAND W = "OWALK_LINK_LIST.COM" 

To make this file a debug initialization file, use the DCL command DEFINE: 

$ DEFINE DBGIINIT [JONES.DBGDIR]DEBUG.INI 
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The debugger will execute the commands in this file before it issues the 
DBG> prompt, as follows: 

VAX-11 DEBUG Version ***** 

•/.DEBUG-1-INITIAL, language is BASIC, module set to ’MEANSUB$MAIN’ 

SET LOG LINK.LOG 

DEFINE/COMMAND W = "(8WALK_LINK_LIST.COM'' 

•/.DEBUG-I-VERIFYICF, exiting indirect command file "DBG$INIT" 

DBG> 


2.5 Language-Dependent and Independent Parameters 

At start up, the debugger displays an informational message in the following 
format: 


VAX-11 DEBUG Version Number 

•/.DEBUG-1-INITIAL, language is xxx, module set to yyy 
DBG> 

The first line of this message identifies the debugger's software version 
number. The second line contains initialization information that identifies the 
current language and program module. The third line contains the debugger 
prompt DBG> . 


2.5.1 Language-Dependent Debugging Parameters 

Debugging parameters influence how the debugger interprets commands and 
how it displays the results of command execution. 

At start up, the debugger sets a default value for each debugging parameter. 
These values may be displayed using the appropriate SHOW command, may 
be altered using the appropriate SET command, and, in some cases, may be 
canceled using the appropriate CANCEL command. 

The default values of some debugging parameters may vary, depending on 
the current language; that is, a particular parameter may have one default 
value if the current language is BASIC and another default value if the 
current language is MACRO. Such parameters are called language-dependent 
debugging parameters. 

The following parameters are language-dependent debugging parameters: 

• MODE 

• RADIX 

• STEP 

• TYPE 

When you change the current language by the SET LANGUAGE command, 
the default values for language-dependent debugging parameters may change. 

To find out what the current language is, issue the SHOW LANGUAGE 
command. 
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2.5.2 Language-Independent Debugging Parameters 

At start up, the default values of two debugging parameters are established 
independently of the current language setting: 

• MODULE 

• SCOPE 

The module parameter allows for the insertion of a module's symbol 
information into the run-time symbol table (RST). At start up, the debugger 
inserts, into the RST, symbol records for the module containing the transfer 
address. The name of this module and the name of the language in which 
the module is written appears in the debugger informational message. 

The transfer address is the location within the compiled code specified by the 
keyword(s) in the source language that signal the beginning of a program. 

For example, in VAX PASCAL the transfer address is the location within the 
compiled code specified by the keyword PROGRAM. 

The scope parameter influences the debugger's interpretation of symbols. 

When you start the debugger with the RUN command, the value of the scope 
parameter is the module that contains the transfer address. When you start 
the debugger with the DEBUG command, the value of the scope parameter is 
the module in which program execution was interrupted. 

Chapter 4 contains a full description of how the module and scope parameters 
affect the debugger's interpretation of symbols. 

You can direct the debugger to keep a record of a debugging session by 
creating a log file. You can also direct the debugger to execute debugger 
commands listed in an external file. Such a file, when executed, is called a 
command procedure. Further, you can direct the debugger to execute a log 
file as a command procedure. This section discusses these topics. 


2.6 Log Files 

A debugger log file is a file containing every debugger command you 
issue during a particular debugging session, together with a display of the 
debugger's response to those commands. 

In a debugger log file, any command you issue in response to the debugger 
prompt (DBG> ) begins a line, but the debugger prompt itself is not recorded. 
The debugger's response to the command appears on the following line or 
lines and, except for an exclamation point at the beginning of each line of 
response, is identical to what you see at your terminal. 

The following is an example of a debugger log file. Note the absence of 
debugger prompts and the presence of exclamation points at the beginning of 
each line of debugger response. 

SHOW OUTPUT 

!output: noverify, terminal, logging to _DB2: [GMF]EV.LOG;1 
SHOW TRACE 

!'/.DEBUG-1-NOTRACES, no tracepoints are set, no opcode tracing 
SET TRACE '/.LINE 30 
SET BREAK '/.LINE 60 
SHOW TRACE 
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Itracepoint at MEANSUB$MAIN '/.LINE 30 
GO 

!routine start at MEANSUB$MAIN 
! trace at MEANSUB$MAIN\'/,LINE 30 
! break at MEANSUB$MAIN\'/,LINE 60 

SET TRACE ‘/.LINE 40 
SHOW TRACE 

Itracepoint at MEANSUB$MAIN\'/,LINE 40 
Itracepoint at MEANSUB$MAIN\*/,LINE 30 

GO ’/.LINE 20 

! start at MEANSUB$MAIN\'/,LINE 30 
! trace at MEANSUB$MAIN\'/,LINE 30 
•trace at MEANSUB$MAIN\'/,LINE 40 
! break at MEANSUB$MAIN\'/.LINE 60 

To create a debugger log file, use the SET OUTPUT command. To name a 
debugger log file, use the SET LOG command. The following subsections 
discuss these commands. 


2.6.1 The SET OUTPUT and SHOW OUTPUT Commands 

The SET OUTPUT command controls the debugger's current output 
configuration; that is, it controls the way in which the debugger's responses 
to commands you issue are displayed and recorded. 

The format of the SET OUTPUT command is 


SET OUTPUT parameter [.parameter...] 

The following is a list of output parameters that you may specify in the SET 
OUTPUT command. 


LOG 

NOLOG 

TERMINAL 

NOTERMINAL 

VERIFY 

NOVERIFY 


Writes debugger output to a log file. If you have not used the 
SET LOG command to name a log file, the debugger uses the 
default file name DEBUG.LOG. 

Does not write debugger output to a log file. This output 
parameter is a default; the debugger does not write output to 
a log file unless you explicitly request it. 

Displays debugger output at the terminal. This output 
parameter is a default; the debugger displays output on 
the terminal unless you explicitly request it not to do so. 

Does not display debugger output, except for diagnostic 
messages, at the terminal. 

Causes the debugger to include in its output each input 
command string in any command procedure or DO clause that 
it is executing; that is, the debugger not only displays the 
results of executing each command in a command procedure 
or DO clause but also displays the commands that caused 
execution. 

Causes the debugger not to include as output each input 
command string that it executes from a command procedure 
or from a DO clause. 

This output parameter is a default; the debugger does not 
display commands that it executes from command procedures 
or DO clauses unless you explicitly direct it to do so. 


2—8 


To see which output parameters are currently in effect, issue the SHOW 
OUTPUT command. 




Controlling the Debugging Environment 


2.6.2 The SET LOG and SHOW LOG Commands 

If the output parameter LOG is in effect (by SET OUTPUT LOG), you can 
direct the debugger to write output to a specified file by issuing the SET LOG 
command in the following format: 

SET LOG file-spec 

The file-spec parameter is the file specification of the file to which you want 
the debugger to write its output. 

If the output parameter LOG is in effect but you have not issued the SET 
LOG command to name a log file, the debugger writes output to a file with 
the default name DEBUG.LOG. 

If the output parameter LOG is not in effect, the debugger does not write 
its output to the file specified in the SET LOG command. However, if you 
subsequently issue a SET OUTPUT LOG command, the debugger begins 
writing output to the file specified in the SET LOG command. 

If the file-spec parameter in the SET LOG command includes both a file name 
and a file type, the debugger writes to the file so specified. 

If the file-spec parameter in the SET LOG command does not include a file 
type, the debugger uses the default file type of LOG. 

To find out the name of the current log file, issue the command SHOW LOG. 

Example 2-1 demonstrates the SET LOG, SHOW LOG, SET OUTPUT, and 
SHOW OUTPUT commands. 


2-9 




Controlling the Debugging Environment 


Example 2-1 Using the SET/SHOW LOG and SET/SHOW 
OUTPUT Commands 


DBG>SET LOG FILE 


IName a log file. 


DBG>SET OUTPUT LOG 


!Write output to the log 
!file. 


DBG>SHOW OUTPUT 

output: noverify, terminal, logging to _DB2:[GMF]FILE.LOG;1 

!Display current output 
!configuration. 

DBG>SH0W LOG !Display name of current 

logging to _DB2:[GMF]FILE.LOG;1 'log file. 

DBG>SET OUTPUT NOTERMINAL,NOLOG 

•/.DEBUG-I-OUTPUTLOST, output being lost, both NOTERMINAL and NOLOG 
are in effect 


DBG>SH0W LOG 

not logging to _DB2:[GMF]FILE.LOG;1 

DBG>SET LOG TERT.EEE !Name a new log file. 

DBG>SH0W LOG !Not logging to TERT.EEE 

not logging to _DB2:[GMF]TERT.EEE;1 !because output is set 

!to NOLOG. 


DBG>SET OUTPUT LOG 


)!Change current output) 
!configuration. 


DBG>SH0W LOG 

logging to _DB2:[GMF]TERT.EEE;1 


output: noverify, noterminal, logging to _DB2:[GMF]TERT.EEE;1 

!Display current output 
!configuration. 


2.7 Command Procedures 

A command procedure is a file containing one or more debugger commands. 
You can cause the debugger to execute debugger commands from a file 
by prefixing the file specification of that file with the at sign (@), in the 
following format: 

©file-spec 

If the file specification includes a file name but not a file type, the debugger 
assumes the default file type COM. 

The @file-spec command may be issued from the terminal, from within a DO 
clause, or from within another command procedure. 

If the @file-spec command is issued from the terminal, the debugger begins 
with the execution of the first command in the file and displays its prompt 
after all commands in the file have been executed. 

If the @file-spec command is one of the commands in a DO clause, the 
debugger begins execution of the first command in the file upon reaching the 
@ file-spec command in the DO clause. After execution of all commands in 
the file, the debugger resumes execution of any remaining commands in the 
DO clause and then issues its prompt. 


2-10 








Controlling the Debugging Environment 


If the @file-spec command is one of the commands in another (calling) 
command procedure, the debugger begins execution of the commands in 
the called command procedure when it reaches the @file-spec command. 

It resumes execution of any remaining commands in the calling command 
procedure after all commands in the called command procedure have been 
executed. 

If the syntax of a command in a command procedure is incorrect, the 
debugger issues an error message and continues execution with the next 
command in the command procedure. 

When the default output parameter NO VERIFY is in effect (see Section 2.5.1), 
the debugger does not display—either on the terminal or in a log file—the 
commands in a command procedure. The debugger simply executes the 
commands and displays the resulting output. 

If you want the debugger to display the commands in a command procedure 
as it executes them, you must set the output parameter to VERIFY (see 
Section 2.5.1). 


2.7.1 


Editor-Created Command Procedures 


You can use an editor to create a command procedure. You do this by 
creating a file and then entering debugger commands into the file. 

For example, the following debugger commands make up the file whose file 
specification is BREAK.EDT: 

SET BREAK/AFTER:3 ‘/.LINE 120 DO (EXAMINE K,N,J,X(K); GO) 

SET BREAK/AFTER:3 ‘/.LINE 160 DO (EXAMINE K,N, J,X(K) ,S; GO) 

SET BREAK 7.LINE 90 

The purpose of the commands in this command procedure is to set 
breakpoints at three different program locations. Thus, whenever the 
command @BREAK.EDT is issued in the debugging session, the debugger 
sets the breakpoints specified in the command procedure. 

The following example is a log file BREAK.LOG that records the use of the 
command procedure BREAK.EDT in a debugging session. 


©BREAK.EDT 

SHOW BREAK 
!breakpoint 
!breakpoint 
X(K),S; GO) 
!breakpoint 
X(K); GO) 


!Cause command procedure to be 
!executed. 

IShow breakpoints set by ©BREAK.EDT. 
at MEANSUB$MAIN\7.LINE 90 

/after:3 at MEANSUB$MAIN\*/,LINE 160 DO (EX K,N,J, 
/after:3 at MEANSUB$MAIN\'/,LINE 120 DO (EX K,N,J, 


GO !Begin program execution. 

!routine start at MEANSUB$MAIN\MEANSUB$MAIN 
! break at MEANSUB$MAIN\MEANSUB$MAIN ‘/.LINE 120 
!MEANSUB$MAIN\MEANSUB$MAIN\K: 3.000000 

!MEANSUB$MAIN\MEANSUB$MAIN\N: 3.000000 

!MEANSUB$MAIN\MEANSUB$MAIN\J: 1.000000 

!MEANSUB$MAIN\MEANSUB$MAIN\X(3): 93.00000 

! start at MEANSUB$MAIN\MEANSUB$MAIN\7.LINE 120 
! break at MEANSUB$MAIN\MEANSUB$MAIN\*/,LINE 160 
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!MEANSUB$MAIN\MEANSUB$MAIN\K: 3.000000 

!MEANSUB$MAIN\MEANSUB$MAIN\N: 3.000000 

!MEANSUB$MAIN\MEANSUB$MAIN\J: 1.000000 

!MEANSUB$MAIN\MEANSUB$MAIN\X(3): 93.00000 

!MEANSUB$MAIN\MEANSUB$MAIN\S: 252.0000 

! start at MEANSUB$MAIN\MEANSUB$MAIN\y.LINE 160 
! break at MEANSUB$MAIN\MEANSUB$MAIN\'/,LINE 90 
CANCEL BREAK/ALL !Cancel all breakpoints. 


2.7.2 Using Log Files as Command Procedures 

You can use a debugger log file as a command procedure. A debugger log file 
contains debugger commands and debugger output; however, the debugger 
output is always preceded on the line by an exclamation point, which signals 
the debugger to ignore the line. 

The exclamation point is called the comment delimiter because it is used to 
delimit comments within the command string. The debugger's use of the 
comment delimiter on its own output in log files makes possible the direct 
use, without modification, of debugger log files as command procedures. 

You request that the debugger execute commands from a log file by specifying 
that file as a command procedure, as follows: 

DBG>®file-spec 

Thus, the log file BREAK.LOG shown in Section 2.6.1 may be used 
as a command procedure in another debugging session by issuing the 
@BREAK.LOG command. When you issue this command in a subsequent 
debugging session, the following debugger commands are executed: 

• @BREAK.EDT 

• SHOW BREAK 

• GO 

• CANCEL BREAK/ALL 

Thus, you can reexecute a previous debugging session by using a log file 
as a command procedure. This feature is helpful if you want to continue 
debugging from where you left off at a previous session. You can also use the 
log file as a command procedure in another program or in a modified version 
of the same program. 


2.8 Interrupting a Debugging Session 

Since the debugger is itself an image within the context of the VAX/VMS 
operating system, it reacts to interruption like other images running in user 
mode; for instance, the image is interrupted (but unchanged), the terminal 
type-ahead buffer is purged, and the DCL command interpreter receives 
control. To interrupt a debugging session, enter CTRL/Y (echoed as *Y) as 
follows: 

DBG> j CTRL/Y 1 

Interrupt 

After you press CTRL/Y, the DCL command interpreter takes control. 
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If you run your program without debugger control, interrupt it, and start the 
debugger with the DEBUG command, the debugger informational message 
indicates the name of the module that contains the program location at which 
program execution was interrupted and the name of the language in which 
that module was written. 

If you run your program with debugger control, you may still need to 
interrupt it by pressing CTRL/Y and then giving the DEBUG command. 

For instance, if your program goes into an infinite loop after you issue the GO 
command, your only option is to press CTRL/Y. In this case, the CTRL/Y- 
DEBUG command sequence brings you back to the DBG> prompt, leaving 
all your debugging parameters as they were. 

You may also need to interrupt a debugger command which is taking too 
long to complete or is generating a large amount of output. In this case, 
the CTRL/Y-DEBUG command sequence causes the debugger to abort the 
current command when all of the data structures are in a consistent state. 


2.8.1 CTRL/Y and CTRL/C 

The effect of issuing CTRL/Y or CTRL/C is the same unless your system or 
application program contains a routine coded to intercept CTRL/C. 

If such a CTRL/C handling routine exists, entering CTRL/C causes control to 
be passed to the handling routine rather than to the command interpreter. 

If a CTRL/C handling routine does not exist, both CTRL/Y and CTRL/C 
interrupt the debugging session and cause control to be passed to the DCL 
command interpreter, which signals with the DCL prompt. 

When the DCL prompt is displayed, you can enter any DCL command. 
Section 2.7.2 discusses the effect of some of these commands in relation to 
restarting a debugging session. 


2.8.2 Options After Interruption 

After interruption of a debugging session by CTRL/Y or CTRL/C and the 

resulting display of the DCL prompt, you may want to enter any of the 

following DCL commands: 

• DEBUG—See Section 2.1.4. 

• CONTINUE—Passes control back to the debugger or to the program, 
whichever had control at the time of interruption. 

• STOP—Causes abnormal termination of the debugger. The debugger exit 
handler is not given control. 

• EXIT—Causes normal termination of the debugger. The debugger exit 
handler is given control. 

• Commands that are performed within the DCL command interpreter— 
These commands may be entered and executed without causing 
termination of the debugger image. For example, after interruption of 
the debugger by CTRL/Y, if you enter the SHOW DAYTIME command 
and follow it with the DEBUG command, control will pass back to the 
debugger. 

• Any other DCL command—Causes termination of the debugger. The 
debugger exit handler is executed. 
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• The SPAWN and ATTACH commands—Allows you to create a 
subprocess or attach to a detached process. See Section 2.7.3. 


2.8.3 The SPAWN and ATTACH Commands 

The debugger provides two commands—SPAWN and ATTACH—that allow 
you to interrupt your debugging session without ending it. 

The debugger command SPAWN acts like the DCL command SPAWN. It 
provides a way of temporarily leaving the debugger for the DCL command 
interpreter. You can also specify SPAWN/NOWAIT with a DCL command. 
This command allows you to continue your debugging session without 
waiting for the spawned subprocess to complete. 

However, if you plan to spawn several times during one debugging session, 
you should use the ATTACH command instead. The ATTACH command 
allows you to go back and forth between a debugging session and the DCL 
command interpreter, or between two debugging sessions. First, you must 
spawn a subprocess; then you can attach to it whenever you want. To return 
to your orginal process, use another ATTACH command. Since you are not 
creating a new subprocess every time you leave the debugger, you are more 
efficiently using system resources. 
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This chapter explains how to start, suspend, and monitor program execution, 
and how to display the current program status. It also discusses how to 
debug exit handlers. 

You can control and monitor program execution by means of all the 
commands discussed in this chapter: STEP, GO, CALL, SHOW CALLS, SET 
BREAK, SET TRACE, and SET WATCH. Refer to the Command Dictionary 
for detailed descriptions of each of these commands. 


3.1 Starting Program Execution 

To begin program execution at debugger start up or to continue program 
execution after interruption, issue the STEP, GO, or CALL command. The 
following sections discuss each of these in turn. 


3.1.1 The STEP Command 

By means of the STEP command, you can control the execution of your 
program. When you issue a STEP command, the debugger responds as 
follows: 

1 It executes one or more instructions. 

2 It reports the line or instruction that follows the last instruction executed. 

3 It reports the source line corresponding to the line or instruction that 
follows the last instruction executed only if the SOURCE parameter is 
in effect by virtue of STEP/SOURCE or SET STEP SOURCE and source 
lines are available. 

4 It issues the DBG> prompt. 

The format of the STEP command is 

STEP [/qualifier...] [integer] 

The decimal integer is an optional parameter that indicates how many lines or 
instructions are to be executed. If the decimal integer is omitted, the debugger 
uses a default value of 1. 

The STEP command qualifiers specify whether the debugger 

• Steps by line or by instruction 

• Steps "into" or "over" called routines in the user program space (user- 
written routines) 

• Steps "into" or "over" called routines in system space 

• Steps to the next branch instruction, call instruction, return instruction, or 
exception condition 

• Displays the messages associated with the step command 
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• Displays lines of source code as it steps 

If STEP command qualifiers are not specified with the STEP command, the 
debugger uses STEP parameters established by the SET STEP command (see 
Section 3.1.1.1, or STEP parameters associated by default with the current 
language. 

The following list describes the effects of the STEP command qualifiers: 


/BRANCH 

/CALL 

/EXCEPTION 

/INSTRUCTION 

/INSTRUCTION=opcode 

Steps to the next branch instruction. 

Steps to the next call instruction. 

Steps to the next exception condition. 

Steps to the next instruction. 

Steps to the instruction whose opcode you specify 
with the code parameter. 

/INTO 

Steps "into" called routines in the user program 
space (and "into" called routines in system space if 
/SYSTEM is also specified); that is, the debugger 
does not differentiate between instructions (or lines) 
within a called routine and those outside of the 
routine as it executes steps. Thus, the execution 
of a STEP command may result in suspension 
of execution within the called routine, in which 
case subsequent step commands will execute the 
instructions (or lines) within that routine. 

/LINE 

/OVER 

Steps to the next line. 

Steps "over" called routines in the user program 
space and in system space; that is, the debugger 
considers any instructions executed as the result 
of a CALL instruction, up to and including the 
corresponding RETURN instruction, to be part of a 
single step. 

/NOSILENT 

Overrides the effect of /SILENT. In other words, the 
"start at" and "stepped to" resume display. 

/NOSOURCE 

Specifies that the debugger not display the line of 
source code that corresponds to the instruction(s) 
being executed. This qualifier does not apply to all 
languages. See Section 3.7 for more information. 

/NOSYSTEM 

Steps "over" called routines in system space. That 
is, the debugger considers any instructions executed 
as the result of a CALL instruction to a routine in 
system space, up to and including the corresponding 
RETURN instruction, to be part of a single step. 

/RETURN 

Causes the debugger to step to the return 
instruction that returns from the current routine. 

It is valid for CALLS and CALLG routines only. 

/SILENT 

Specifies that the "stepped to" message associated 
with the STEP command not be displayed. The 
/SILENT qualifier is most useful in command 
procedures or in DO clauses when you do not 
want the customary output from a STEP command. 
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Specifies that the debugger display the line of 
source code that corresponds to the instruction(s) 
being executed. This qualifier does not apply to all 
languages. See Section 3.7 for more information. 

Steps "into" called routines in system space, 
provided that /INTO is also specified; that is, 
the debugger, in its execution of steps, does not 
differentiate between instructions (or lines) within a 
called routine in system space and those outside of 
system space. Thus, execution of a STEP command 
may result in suspension of execution in system 
space. 

When a qualifier is specified with the STEP command, it temporarily overrides 
the STEP parameter established by the SET STEP command or the default 
STEP parameter associated with the current language. 


3.1.1.1 The SET STEP and SHOW STEP Commands 

The SET STEP command sets the default step parameters; that is, it 
establishes the STEP parameters that the debugger uses whenever a STEP 
command is issued without a STEP command qualifier. 

When a STEP parameter is specified as a qualifier in the STEP command, it 
overrides, for the duration of the command, any step parameters established 
by the SET STEP command or any step parameters associated with the 
current language. 

As described in Section 3.3.1, step parameters may be any of the 
following: BRANCH, CALL, EXCEPTION, LINE, INSTRUCTION, 
INSTRUCTION=opcode, INTO, OVER, NOSILENT, NOSOURCE, 
NOSYSTEM, RETURN, SILENT, SOURCE, or SYSTEM. Note, however, 
that a step parameter is not prefixed with a slash unless it is used as a STEP 
command qualifier. 

The following is the format of the SET STEP command: 

SET STEP step-parameter [.step-parameter...] 

Note that default step parameters are associated with each language. Thus, 
when you change languages by using the SET LANGUAGE command, the 
default step parameters may also change. 

To display the current step parameters, issue the SHOW STEP command. 

At the assembly level, program locations are often specified by virtual 
addresses or by offsets from program labels, rather than by symbols. Thus, it 
is common to use virtual addresses as parameters in commands such as STEP 
that affect program execution. 

So, if you are debugging assembly-level code, you may find it useful to 
set the STEP parameter to INSTRUCTION. Then, whenever you issue a 
STEP command, you will advance by one instruction or by the number of 
instructions you specify as a parameter in the STEP command. By single 
stepping, you can literally read your program's source code at the assembly 
level as VAX instructions. 

Further, you may want to set STEP parameters to INTO to enable you to 
step through the called routines in your program. Then whenever program 
execution reaches a routine call, you can follow program flow through the 
called routine (a single instruction at a time or by lines). 


/SOURCE 


/SYSTEM 
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Example 3-2 demonstrates the use of the STEP command. 

Example 3-2 Using the SET/SHOW STEP Commands 


DBG>SH0W STEP ‘Display current step parameters, 

step type: nosystem, source, nosilent, over routine calls, by line 

DBG>SH0W MODE !Display current modes, 

modes: symbolic, d_float, noscreen, nokeypad 
input radix : decimal 
output radix: decimal 

DBG>SET STEP INSTRUCTION, INTO, NOSOURCE !Set STEP parameters. 


DBG>SH0W STEP !Display current step parameters, 

step type: nosystem, nosource, nosilent, into routine calls, by instruction 


DBG>STEP 

stepped to CIRCLE '/.LINE 2 : PUSHAL L~512 


IStep through the program. 


DBG>STEP 

stepped to CIRCLE '/.LINE 2 +6: MNEGL #2,-(SP) 


DBG>STEP 

stepped to CIRCLE %LINE 2 +9: CALLS #2,L~F0R$WRITE_SF 


DBG>STEP 

stepped to F0R$WRITE_SF+2: JMP 


L~56758 IStep into a called routine 
!named FOR$WRITE_SF. 
lOnce the 2-byte entry mask is 
!stepped by, the debugger 
!references instructions by 
!their virtual address; this 
lis because FOR$WRITE_SF is 
Inot in the run-time symbol 
!table. 


DBG>STEP 

stepped to 56758: MOVZBL #1,R0 
DBG>STEP 

stepped to 56761: BRW 56870 


DBG>STEP/RETURN 
stepped to 58561: RET 

DBG>STEP 

stepped to CIRCLE '/.LINE 4 : PUSHAL L~535 
DBG>STEP 

stepped to CIRCLE '/.LINE 4 +6: MNEGL #3,-(SP) 

DBG>STEP 

stepped to CIRCLE 7.LINE 4 +9: CALLS #2, L~FOR$READ_SF 
DBG>STEP 

stepped to F0R$READ_SF+2: JMP L~56646 IStep into the called 

I routine FOR$READ_SF. 

DBG>STEP 

stepped to 56646: MOVZBL #2,R0 
DBG>STEP 

stepped to 56649: BRW 56870 


I Return from FOR$WRITE_SF. 

I Begin executing main program. 


DBG>G0 

'/.DEBUG-I-EXITSTATUS, is 


*'/.SYSTEM-S-NORMAL, normal successful completion* 
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3.1.2 The GO Command 

You can use the GO command under three circumstances: 

• To begin execution of your program at debugger start up, in which case 
execution begins from the transfer address 

• To resume execution at the instruction following the last instruction 
executed, in which case you do not specify an address expression as a 
parameter in the GO command 

• To resume execution at a specified program location, in which case you 
specify the corresponding address expression as a parameter in the GO 
command 

Unlike the STEP command, which suspends execution after a specified 
number of instructions or lines have been executed, the GO command will 
cause your program to continue executing until one of the following occurs: 

• The program terminates. 

• A breakpoint is reached. 

• A watchpoint is activated. 

• An exception occurs. 

• The program is interrupted by CTRL/Y or CTRL/C. 

The following is the format of the GO command: 

GO [addres8-expression] 

If an address expression is specified as a parameter in the GO command, the 
debugger begins program execution at the location specified by the address 
expression. 

Using an address expression as a parameter in the GO command may be 
helpful when you want to reexecute sections of your program but do not 
want to start all over again. Note, however, that when you specify an 
address-expression parameter in the GO command, the program state at the 
location denoted by the address expression must be identical to the program 
state at the time you issue the GO command; otherwise, results may be 
unpredictable. 

See Section 3.2.1.1 for examples of how to use the GO command. 


3.1.3 The CALL Command 

The CALL command is useful in debugging routines in your program. 

When you issue a CALL command, the debugger takes the following action: 

1 Saves the current values of the general registers 

2 Constructs an argument list 

3 Executes a call to the routine specified in the command and passes any 
arguments 

4 Executes the routine 

5 Displays the value returned by the routine in RO 
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6 Restores the values of the general registers to the values they had just 
previous to the CALL command 

7 Issues its prompt 

The debugger executes a routine called by the CALL command whether 
or not your program actually includes a call to that routine, so long as the 
routine was linked with your program. 

You can also debug unrelated routines by linking them with a dummy main 
module that has a transfer address and then using the CALL command to 
execute them. 

The following is the format of the CALL command: 

CALL routine-name [(argument1[.argument2...])] 

Note that any arguments must be enclosed in parentheses. 


3.2 Suspending Program Execution 

The following sections discuss how to suspend program execution by setting 
breakpoints, exception breakpoints, and watchpoints. 


3.2.1 Breakpoints 

A breakpoint is a program location at which the debugger performs the 
following actions: 

1 Suspends program execution 

2 Checks the AFTER count and resumes program execution if the specified 
number of breakpoint activations has not yet been reached 

3 Evaluates the WHEN clause (if it is present) and resumes execution if it 
evaluates as FALSE in the current language 

4 Displays the name or the virtual address of the location at which 
execution has been suspended 

5 Executes commands in a DO clause if one was specified in the SET 
BREAK command 

6 Issues the DBG> prompt 

To set a breakpoint, issue the SET BREAK command in the following format. 

SET BREAK [/qualifier...] [address-expression - 
[.address-expression,...]] [WHEN (expression)] - 
[DO (command [;command...])] 

When you specify an address expression on the SET BREAK command, the 
breakpoint is then associated with the given program location. Specifying a 
list of address expressions is equivalent to setting more than one breakpoint 
(one for each location in the list). When the debugger breaks at the given 
address, it suspends execution before executing the instruction at that location 
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Some of the command qualifiers (/BRANCH, /CALL, /EXCEPTION, 
/INSTRUCTION[=opcode], and /LINE) indicate classes of conditions on 
which the breakpoint should be taken. For example, SET BREAK/CALL tells 
the debugger to break at every call to a subroutine. If you specify one of 
these qualifiers, you should not specify an address expression. 

The /RETURN qualifier specifies that the break is to be taken not at the 
given address but rather at the return statement of the routine containing the 
address. In other words, "SET BREAK/RETURN routine" breaks at the return 
from the routine rather than at the entry to the routine. 

Other qualifiers on the SET BREAK command include /AFTER:n, /SILENT, 
/SOURCE, and /TEMPORARY. These qualifiers generally affect what output 
you see at the breakpoint or whether the breakpoint is taken. See the SET 
BREAK command in the Command Dictionary for more details. 

If you specify a WHEN clause, the debugger evaluates it; if the expression 
in a WHEN clause evaluates as TRUE in the current language, break action 
occurs. However, if the clause evaluates as FALSE, break action does not 
occur, the commands specified in the DO command list are not executed, and 
program execution is continued. 

If you specify a DO clause, the debugger executes commands in the DO 
clause when the breakpoint is activated. See Section 3.2.1.1. 

If you use a virtual memory address or an address expression whose value 
is not a symbolic location as a parameter in the SET BREAK command, you 
should check that an instruction actually begins at the byte of memory so 
indicated. If an instruction does not begin at this byte, a run-time error may 
occur when an instruction including that byte is executed. Note that when 
the breakpoint is set, the debugger does not verify that the location specified 
marks the beginning of an instruction. 

When a routine name is the parameter in a SET BREAK command, the 
debugger notes this fact when the breakpoint is activated by issuing the 
following message: 

routine break at routine name 

Routine breakpoints are special cases because the breakpoint is actually set at 
the memory address 2 bytes greater than the memory address of the routine 
name itself (called the entry point). This is done so that the breakpoint is 
not set on the 2-byte entry mask of the routine, but is set instead at the first 
instruction in the routine, which begins directly following the entry mask. 

Note that the command 

DBG> EXAMINE routine-name 

does not skip over the routine entry mask. Therefore, to examine the first 
instruction in the routine, you must issue the command 

DBOEXAMINE routine-name + 2 

To see what breakpoints are in effect, issue the SHOW BREAK command. 

Once set, a breakpoint remains active for the duration of the debugging 
session unless you cancel it with the CANCEL BREAK command or set 
another breakpoint, watchpoint, or tracepoint at that program location. In 
that case the old breakpoint specification is overwritten. 
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To cancel one or more breakpoints, issue the CANCEL BREAK command in 
the following format: 

CANCEL BREAK [/qualifier] [address-expression - 
[.address-expression,...]] 

If you specify an address-expression parameter, the breakpoint at the location 
denoted by the address expression is canceled. In this case, you cannot also 
specify a command qualifier. 

If you specify the /ALL command qualifier, all breakpoints are canceled. In 
this case, you cannot also specify an address-expression parameter. 

Example 3-3 shows how breakpoints and watchpoints may be set, canceled, 
and overwritten. 


Example 3-3 Setting, Showing, and Canceling Eventpoints 


DBG>SET BREAK '/.LINE 15 


!Set breakpoint. 

DBOSHOW BREAK 

breakpoint at TOYV/.LINE 15 


!Show breakpoint. 

DBOCANCEL BREAK '/.LINE 15 


!Cancel breakpoint. 

DBOSHOW BREAK 

y.DEBUG- 1-NOBREAKS, no breakpoints 

are set 


DBOSET BREAK '/.LINE 15 


!Set breakpoint. 

DBOSET WATCH y,LINE 15 


!Set watchpoint at 
!same location. 

DBOSHOW BREAK 

y.DEBUG-1-NOBREAKS, no breakpoints 

are set 

!Breakpoint is 
•overwritten. 

DBOSHOW WATCH 

watchpoint at T0Y\y,LINE 15 for 4. 

bytes. 

!Watchpoint set. 

DBOSET BREAK '/.LINE 15 


!Set breakpoint. 

DBOSET BREAK/AFTER: 5 '/.LINE 15 


!Set modified 
!breakpoint at 
!same location. 

DBOSHOW BREAK 

breakpoint /after:5 at T0YV/.LINE 15 

!Previous breakpoint 
!overwritten. 


Note that the following commands overwrite one another when they contain 
identical address-expression parameters: 

• SET BREAK (in all its forms) 

• SET TRACE 

• SET WATCH 
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3.2.1.1 Command Sequence at Breakpoint 

If you want the debugger to execute one or more debugger commands 
immediately after a breakpoint has been reached, you specify these 
commands in a DO clause as shown in the following format: 

SET BREAK address-expression DO (command [;command...] ) 

Whether the DO clause includes one or more commands or invokes a 
command procedure, parentheses are required delimiters, as shown in the 
format above. If the DO clause includes a list of commands, you must 
separate commands with a semicolon. 

The debugger executes commands in a DO clause in the order in which 
they are listed. If one of the commands is a command procedure (see 
Section 2.6), the debugger begins execution of the commands in that file 
when it reaches the command file specification (@file-spec) in the DO clause. 
After the debugger has executed each command in the command procedure, 
it continues executing commands in the DO clause until it exhausts them or 
until it reaches another command file specification. 

The DO clause may contain commands that resume program execution. For 
example, a typical DO clause might contain several EXAMINE commands 
followed by a GO command. 

Note that the debugger does not check the syntax of the commands within 
a DO clause after you issue the SET BREAK command containing that 
DO clause; the debugger checks for syntax when it actually executes the 
commands in the DO clause at breakpoint activation. 

Any debugger command, including a SET BREAK command with a DO 
clause, may appear in a DO clause. Nesting of DO clauses is permissible to 
any level, so long as syntax rules have not been violated. 

You are not limited in the number and type of debugger commands you can 
include in a DO clause. If all the commands you want to include in the clause 
do not fit on a single input line, specify the line continuation character (-) 
at the end of the input line and then press RETURN. In this way, you can 
continue entering commands within the same DO clause. 

If you want the commands in the DO clause to be executed conditionally, 
include a WHEN clause in the SET BREAK command, as follows: 

SET BREAK address-expression WHEN (expression) - 
DO (command [;command...] ) 

The WHEN clause specifies any expression in the currently set language 
that you want logically evaluated every time the breakpoint occurs. If the 
expression is true, break action occurs. If it is false, break action does not 
occur, and the command specified by the DO command list is not executed. 

Example 3-4 demonstrates the power and versatility of the DO clause at 
breakpoint. 
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Example 3-4 Using SET BREAK in a DO Clause 


DBG>SET BREAK '/.LINE 16 DO (EXAMINE I; EXAMINE R; STEP) 


dbg>go 

routine start at TOY 
break at T0YV/.LINE 16 
T0Y\I: 1 

TOY\R: 0.0000000E+00 
start at T0YV/.LINE 16 
stepped to TOYV/.LINE 17 

DBG>SET BREAK ‘/.LINE 16 DO (EXAM 


!Start at routine. 

!Break at line 16. 

!EXAMINE I in DO clause. 

!EXAMINE R in DO clause. 

!STEP in DO clause. 

I; EXAM R; GO '/.LINE 15) 

!This command causes the 
!execution of an infinite 
Hoop once the breakpoint 
!at line 16 is activated. 


DBG>G0 ‘/.LINE 15 

start at T0YY/.LINE 15 
break at TOYY/.LINE 16 
T0Y\I: 1 

T0Y\R: 0.0000000E+00 
start at TOYY/.LINE 15 
break at T0YY/.LINE 16 
T0Y\I: 1 

T0Y\R: 0.0000000E+00 
start at T0YY/.LINE 15 
break at T0YV/.LINE 16 
TOY\I: 1 

T0Y\R: 0.0000000E+00 
start at T0Y\'/,LINE 15 
break at T0Y\7.LINE 16 

| CTRL/Y | 

Interrupt 

$ 


!Begin execution. 

!Breakpoint activated. 
!EXAMINE I. 

!EXAMINE R. 

! GO '/.LINE 15. 

!Breakpoint activated. 
{EXAMINE I. 

{EXAMINE R. 

! GO ‘/.LINE 15. 
{Breakpoint activated. 
!and so on. 


{Interrupt by CTRL/Y. 


3.2.2 Exception Breakpoints 

An event arising within the context of an executing program may require the 
execution of software outside that program's explicit flow of control. The 
notification of such an event is called an exception, and the presence of an 
exception indicates that a "condition" exists. Exception conditions range in 
severity and vary in the way they affect an executing program. The following 
are examples of exception conditions: 

• An arithmetic overflow or underflow 

• A memory access violation 

• An invalid operation code 

• A division by zero 

You direct the debugger to treat an exception generated by your program as 
a breakpoint by issuing the SET BREAK/EXCEPTION command. Specifying 
the command SET EXCEPTION BREAK has the same effect. As a result of 
this command, whenever your program generates an exception condition, the 
debugger responds by suspending program execution, reporting the exception 
condition, and prompting you for input. 
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Whenever an exception breakpoint is activated, therefore, you have the 
opportunity to issue debugger commands. When you want to continue 
program execution, you can specify one of the following commands: 

• A GO command without an address-expression parameter—In this 
case, the debugger fields and resignals the exception, thus allowing any 
user-declared exception handlers to execute. 

• A GO command with an address-expression parameter—In this case, the 
debugger allows program execution to continue at the specified location, 
thus inhibiting the execution of any user-declared exception handlers. 

Note that you cannot issue a STEP command to resume program execution 
after breakpoint activation. The STEP command is illegal in this context and, 
if issued, will result in a warning message. 

If you do not specify an exception breakpoint with the SET BREAK 
/EXCEPTION command or if you cancel an exception breakpoint with 
the CANCEL BREAK/EXCEPTION command, exception conditions generated 
by your program are handled in the following way: 

1 The debugger fields and resignals the exception. 

2 If you have defined a condition handler in your program, it is executed. 

3 If you have not defined a condition handler or if a condition handler that 
you have defined resignals the exception condition, a diagnostic message 
is issued and control is returned to the debugger, which then displays its 
prompt. 

Note that an exception handler executes until one of the following occurs: 

• The exception handler "handles" the condition, thus allowing the program 
to continue execution. 

• The exception handler resignals the exception condition. 

• The exception handler encounters a breakpoint or watchpoint. 

• The exception handler generates its own exception. 

• The exception handler exits, thus terminating program execution. 

You cancel the SET BREAK/EXCEPTION command by issuing the CANCEL 
BREAK/EXCEPTION command. 

When debugging exceptions, you can use the following four built-in symbols 
which provide a means of qualifying exception breakpoints. 

• %EXC_FACILITY 

• %EXC_NAME 

• %EXC_NUMBER 

• %EXC_SE VERITY 

The %EXC_FACILITY built-in symbol returns the facility of the current 
exception. For example: 

DBG> EVALUATE 7.EXC_FACILITY 
"SYSTEM" 

DBG> SET BREAK/EXCEPTION WHEN C/.EXC_FACILITY * "SYSTEM") 
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The %EXC_NAME built-in symbol returns the name of the current exception. 
For example: 

DBG> EVALUATE 7.EXC.NAME 

"FLTDIV.F" 

DBG> SET BREAK/EXCEPTION WHEN (*/,EXC_NAME = "FLTDIV.F") 

The %EXC_NUMBER built-in symbol returns the current exception number. 
For example: 

DBG> EVALUATE ‘/.EXC_ NUMBER 
12 

DBG> EVALUATE/CONDITION.VALUE */.EXC_NUMBER 

%SYSTEM-F-ACCVIO, access violation at PC virtual address 
DBG> SET BREAK/EXCEPTION WHEN (*/.EXC_NUMBER = 12) 

The %EXC_SEVERITY built-in symbol returns the severity code of the 
current exception. For example: 

DBG> EVALUATE 7.EXC.SEVERITY 

tipM 

DBG> SET BREAK/EXCEPTION WHEN C/.EXCL SEVERITY = "F") 

For more information on exceptions, consult any of the following sources: the 
VAX Architecture Handbook , the VAX/VMS System Services Reference Manual , 
or the VAX/VMS Run-Time Library Routines Reference Manual. 


3.2.3 Watchpoints 

You can direct the debugger to watch an entity and notify you if its value 
is modified. To do this, you specify as a parameter in the SET WATCH 
command an address expression that identifies the location where the entity 
resides. The format of the SET WATCH command is 

SET WATCH [/qualifier] address-expression - 
[.address-expression,...] [WHEN (expression)] - 
[DO (commancLlist)] 

As a result of the SET WATCH command, the debugger sets a watchpoint at 
the program location specified by the address expression. 

If the entity has a compiler-generated type, the debugger uses the length 
in bytes associated with that type to determine the length in bytes of the 
watched location. If the entity does not have a compiler-generated type, the 
debugger watches 4 bytes of virtual memory, beginning at the byte identified 
by the address expression. 

The SET WATCH qualifiers include /AFTER:n, /SILENT, /SOURCE, and 
/TEMPORARY. For detailed information about these qualifiers, see the 
Command Dictionary. 

If you specify a WHEN clause, the debugger evaluates it; if the expression 
in WHEN clause evaluates as TRUE in the current language, watch action 
occurs. However, if the clause evaluates as FALSE, watch action does not 
occur, the commands specified in the DO command list are not executed, and 
program execution is continued. 

If you specify a DO clause, the debugger executes commands in the DO 
clause when the watchpoint is activated. See Section 3.2.1.1. 
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Whenever an instruction causes the modification of a watched entity, the 
debugger performs the following operations: 

1 Suspends program execution after that instruction has completed 
execution 

2 Checks the AFTER count and resumes program execution if the specified 
number of breakpoint activations has not yet been reached 

3 Evaluates the WHEN clause (if it is present) and resumes execution if it 
evaluates as FALSE in the current language 

4 Displays the name or the virtual address of the location at which 
execution has been suspended 

5 Executes commands in a DO clause if one was specified in the SET 
WATCH command 

6 Identifies the instruction that modified the entity 

7 Reports the old value of the entity 

8 Reports the new (modified) value of the entity 

9 Issues the DBG > prompt 

To display watchpoints currently in effect, issue the command SHOW 
WATCH. 

To cancel a watchpoint, issue the CANCEL WATCH command in the 
following format: 

CANCEL WATCH [/qualifier] [address-expression - 
[.address-expression,...]] 

If you specify an address-expression parameter, the watchpoint at the location 
denoted by the address expression is canceled. In this case, you cannot also 
specify a command qualifier. 

If you specify the /ALL command qualifier, all watchpoints are canceled. In 
this case, you cannot also specify an address-expression parameter. 

You can set watchpoints on aggregates (that is, entire arrays or records). A 
watchpoint set on an array or record will trigger if any element of the array 
or record changes. Thus, you do not need to set watchpoints on individual 
array elements or record components. Note, however, that you cannot set an 
aggregate watchpoint on a variant record. 

Example 3-5 demonstrates the SET WATCH, SHOW WATCH, and CANCEL 
WATCH commands. 
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Example 3-5 Using the SET/SHOW/CANCEL WATCH 
Commands 


DBG>SET WATCH RESULT 


!Set watchpoint at 
•RESULT. 


DBG>SH0W WATCH 
watchpoint of TOTAL\RESULT 


dbg>go 

start at T0TAL\START+O2 

write to TOTAL\RESULT at PC T0TAL\G03 

old value = 0000000 

new value = 00000A66 


!Display watch- 
!points. There are 
!4 bytes watched 
!beginning at 
!TOTAL\RESULT. 

!Notification of 
!watchpoint modifi- 
!cation. Note that 
!T0TAL\G03 identi¬ 
fies the location 
!of the instruction 
{that caused the 
{modification of 
{RESULT. 


DBG>SH0W MODE 

modes: symbolic, d_float, noscreen, nokeypad 

input radix : hexadecimal 
output radix: hexadecimal 

{Values are 
{displayed in hexa- 
!decimal. Addre s s 
{expressions are 
{displayed symboli¬ 
cally where possi¬ 
ble. 


DBG>SH0W WATCH {Watchpoint still in 

watchpoint at TOTAL\RESULT for 4. bytes. {effect. 


DBG>CANCEL WATCH RESULT 


{Cancel the watch- 
!point. 


DBG>SH0W WATCH {Show current watch- 

'/.DEBUG-1-NOWATCHES, no watchpoints are set {points. 


DBG> SET WATCH ARR 


DBG> GO 

watch of SUBR\ARR at SUBRY/.LINE 12+8 
old value: 


(1) : 7 

( 2 ) : 12 

(3) : 3 

(4) : 0 


!Set watchpoint on 
{array ARR. 

{Watchpoint triggers 
{when any element 
!of ARR changes. 

!Here, the third 
{element changed. 


new value: 

(1) : 7 

( 2 ) : 12 

(3) : 28 

(4) : 0 


break at SUBRY/.LINE 14 


3.2.3.1 Watchpoint Restrictions 

The mechanism for implementing watchpoints is to establish write protection 
for the page of memory that contains the watchpoint; consequently, when a 
write operation to that page is attempted, an exception occurs. The debugger 
handles the exception. It temporarily unprotects the page to allow the 
instruction to complete and then it determines whether the watched variable 
was modified. 
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Because problems would arise if the stack were write protected, currently you 
cannot set watchpoints on variables that are allocated on the stack. 


3.3 Monitoring Program Execution 

This section discusses how to monitor program execution by tracing the flow 
of program control and by displaying the current state of procedure calls. 


3.3.1 Tracepoints 

By setting tracepoints, you can monitor the sequence in which instructions 
in your program are executed and thereby check for unexpected control 
transfers. Moreover, tracepoints do not interrupt or otherwise disturb program 
execution. 

When a tracepoint is activated, the debugger performs the following steps: 

1 Suspends program execution 

2 Checks the AFTER count and resumes program execution if the specified 
number of tracepoint activations has not yet been reached 

3 Evaluates the WHEN clause (if it is present) and resumes execution if it 
evaluates as FALSE in the current language 

4 Displays the name or the virtual address of the location at which 
execution has been suspended 

5 Executes commands in a DO clause if one was specified in the SET 
TRACE command 

6 Reports that execution has reached the traced location 

7 Resumes execution at the point of suspension 

To set a tracepoint, issue the SET TRACE command in the following format: 

SET TRACE [/qualifier] [address-expression - 
[.address-expression,...]] [WHEN (expression)] - 
[DO (command-list)] 

A tracepoint has the same effect as a breakpoint except that program 
execution resumes immediately after a tracepoint has been taken. The syntax 
of the SET TRACE command and the SET BREAK command is the same. 
Also, the command qualifiers and their meanings are the same for the two 
commands. 

If you specify the /CALL or the /BRANCH command qualifier, the debugger 
sets tracepoints at all instructions that are members of the family of CALL 
or BRANCH instructions, respectively (see Section 3.3.1.1). In this case, 
you cannot also specify an address-expression parameter. SET TRACE 
/INSTRUCTION will trace every instruction that gets executed. 

To see what tracepoints are in effect, issue the command SHOW TRACE. 

To cancel one or more tracepoints, issue the CANCEL TRACE command in 
the following format: 

CANCEL TRACE [/qualifier] [address-expression - 
[address-expression,...]] 
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If you specify an address-expression parameter, the debugger cancels the 
tracepoint at the location denoted by the address expression. In this case, you 
cannot also specify a command qualifier. 

If you specify the /CALL or the /BRANCH command qualifier, the debugger 
cancels tracepoints at all instructions that are members of the family of CALL 
or BRANCH instructions, respectively. In this case, you cannot also specify 
an address-expression parameter. 

If you specify the /ALL command qualifier, the debugger cancels all 
tracepoints. In this case, you cannot also specify an address-expression 
parameter. 

Example 3-6 demonstrates the use of the SET, SHOW, and CANCEL TRACE 
commands. 

Example 3-6 Using the SET/SHOW/CANCEL TRACE 
Commands 


DBOSHOW TRACE 

'/.DEBUG-1-NOTRACES, no tracepoints 


are set, no opcode tracing 

IShow tracepoints in 
!effect. 


DBG>SET TRACE '/.LINE 30 


!Set tracepoint at '/.LINE 
!30. 


DBG>SET BREAK '/.LINE 60 


!Set breakpoint at '/.LINE 
!60. 


DBOSHOW TRACE IShow tracepoints in 

tracepoint at MEANSUB$MAIN\'/.LINE 30 !effect. 


DBG>G0 

routine start at MEANSUB$MAIN 
trace at MEANSUB$MAIN\'/.LINE 30 
break at MEANSUB$MAIN\'/,LINE 60 


!Begin program execution. 
!Start of program. 

!Tracepoint reached. 

!Breakpoint reached. 


DBG> SET TRACE '/.LINE 40 


!Set another tracepoint. 


DBOSHOW TRACE 

tracepoint at MEANSUB$MAIN\'/,LINE 40 
tracepoint at MEANSUB$MAIN\'/,LINE 30 

DBOGO '/.LINE 20 
start at MEANSUB$MAIN\'/,LINE 20 
trace at MEANSUB$MAIN\'/.LINE 30 
trace at MEANSUB$MAIN\'/.LINE 40 
break at MEANSUB$MAIN\'/,LINE 60 


IShow tracepoints in 
!effect. 


!Resume execution at 
! '/.LINE 20. 

!Tracepoint reached. 
!Tracepoint reached. 
{Breakpoint reached. 


DBG> CANCEL TRACE '/.LINE 40 


!Cancel one tracepoint. 


DBOSHOW TRACE IShow tracepoints in 

tracepoint at MEANSUB$MAIN\'/,LINE 30 I effect. 


DBG> CANCEL TRACE/ALL 


I Cancel all tracepoints. 


DBOSHOW TRACE 

'/.DEBUG-1-NOTRACES, no tracepoints 


are set, no opcode tracing 

IShow tracepoints in 
I effect. 


3.3.1.1 Opcode Tracing 

Opcode tracing is the tracing of all instructions or the tracing of a family of 
instructions. 
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When you issue SET TRACE/INSTRUCTION, the debugger traces all 
instructions. When you issue the command SET TRACE/CALL, the debugger 
traces any of the following instructions: CALLS, CALLG, BSBW, BSBB, JSB, 
RSB, RET. 

If you issue the command SET TRACE/BRANCH, the debugger traces any of 
the following instructions: 


ACBB 

BBSS 

BNEQ 

ACBL 

BBSSI 

BRB 

ACBQ 

BEQL 

BRW 

ACBD 

BGEQ 

BVC 

ACBG 

BGEQU 

BVS 

ACBH 

BGTR 

CASEB 

AOBLEQ 

BGTRU 

CASEL 

AOBLSS 

BLBC 

CASEW 

BBC 

BLBS 

JMP 

BBCC 

BLSS 

SOBGEQ 

BBCCI 

BLSSU 

SOBGTR 

BBCS 

BLEQ 


BBS 

BLEQU 



Note that you can also trace general lists of opcodes. For instance, SET 
TRACE/INSTRUCTIONSADDL3,MULL3) traces all ADDL3 and MULL3 
instructions. 

To see the tracepoints currently in effect, issue the command SHOW TRACE. 

To cancel tracepoints at CALL or BRANCH instructions, use the CANCEL 
TRACE command with the appropriate qualifier, as follows: 

DBG>CANCEL TRACE/CALL 
DBOCANCEL TRACE/BRANCH 

Note that opcode tracing noticeably slows program execution. 

Example 3-7 demonstrates the use of the /CALL and /BRANCH qualifiers in 
the SET, SHOW, and CANCEL TRACE commands. 
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Example 3-7 Using the /CALL and /BRANCH Qualifiers with SET TRACE 


DBG>SET TRACE/CALL 


!Trace call instructions. 


DBOSHOW TRACE IShow tracepoints in effect, 

tracing /CALL instructions: CALLS, CALLG, BSBW, BSBB, JSB, RSB and RET 


DBG>G0 ‘/.LINE 20 

MEANSUB$MAINV/.LINE 20 

MEANSUB$MAINV/.LINE 30 +9: 
24566: JSB <8B~4(AP) 
MEANSUB$MAIN\%LINE 200 +7 
24918: CALLS #4,W~24987 
25003: JSB L~8352 
8407: JSB L~94721 
94877: RSB 
8492: RSB 

25190: JSB L~34295 
34333: RSB 


start 

at 

ME/ 

trace 

at 

PC 

trace 

at 

PC 

trace 

at 

PC 

trace 

at 

PC 

trace 

at 

PC 

trace 

at 

PC 

trace 

at 

PC 

trace 

at 

PC 

trace 

at 

PC 

trace 

at 

PC 


!Begin program execution. 
CALLS \#1,L~BAS$INIT_GOSUB 
CALLS \#1,L~BAS$PRINT 


DBOSHOW TRACE 

tracing /CALL instructions: 


IShow tracepoints in effect. 
CALLS, CALLG, BSBW, BSBB. JSB, RSB and RET 


DBOSET TRACE/BRANCH 


!Trace all branch 
!instructions. 


DBOSHOW TRACE IShow tracepoints in effect, 

tracing /CALL instructions: CALLS, CALLG, BSBW, BSBB, JSB, RSB and RET 
tracing /BRANCH instructions: BNEQ, BEQL, BGTR, BLEQ, BGEQ, 

BLSS, BGTRU, 

BLEQU, BVC, BVS, BGEQU, BLSSU, BRB, BRW, JMP, BBS, BBC. 

BBSS, BBCS, 

BBSC, BBCC, BBSSI, BBCCI, BLBS, BLBC, ACBB, ACBW, ACBL, 

ACBF, ACBD, 

ACBG, ACBH, AOBLEQ, AOBLSS, SOBGEQ, SOBGTR, CASEB, CASEW 
said CASEL 


(Continued on next page) 
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Example 3-7 (Cont.) Using the /CALL and /BRANCH Qualifiers with SET TRACE 


DBG>G0 '/.LINE 20 ! Resume program execution 

start at MEANSUB$MAIN\'/.LINE 20 ! at '/.LINE 20. 

trace at PC MEANSUB$MAIN\'/.LINE 30 +9: CALLS \#1 ,L~BAS$INIT_GOSUB 

routine trace at PC BAS$INIT_G0SUB: JMP L~24510 

trace at PC 24552: BBC #11,B~-26(R0),24559 

trace at PC 24566: JSB «B~4(AP) 

trace at PC MEANSUB$MAIN\'/,LINE 200 +7: CALLS \#1 ,L~BAS$PRINT 

routine trace at PC BAS$PRINT: JMP L "'24896 

trace at PC 24906: BNEQ 24913 

trace at PC 24911: BRB 24916 

trace at PC 24918: CALLS #4,VT24987 

trace at PC 25003: JSB 1~8352 

trace at PC 8359: BGTR 8366 

trace at PC 8364: BGEQ 8377 

trace at PC 8391: BEQL 8407 

trace at PC 8407: JSB L~94721 

trace at PC 94728: BLBS L~103336,94740 

R2,L~104364,94762 
94790 
94817 
94829 

B~4(SP),94869 


trace at PC 94752: 
trace at PC 94772: 
trace at PC 94804: 
trace at PC 94815: 
trace at PC 94860: 
trace at PC 94877: 
trace at PC 8413: 


BBCS 

BEQL 

BEQL 

BRB 

BLBC 

RSB 

CASEL 


RO,#1,#2 


8431, 

8431, 

8458 


trace at PC 8437: BNEQ 8444 


DBG>CANCEL TRACE/ALL !Cancel all tracepoints. 

DBG>SH0W TRACE IShow tracepoints in effect. 

'/.DEBUG-1-NOTRACES, no tracepoints are set, no opcode tracing 


3.3.2 The SHOW CALLS Command 

When procedure A calls procedure B (by means of a CALL instruction), 
the VAX/VMS operating system preserves information about the program 
state of procedure A at the time that control is transferred to procedure B. 
This information is stored on the stack in a call frame for procedure B. The 
execution of a CALL instruction, therefore, results in the construction of a call 
frame for the called routine; this call frame contains information about the 
calling routine. 

If procedure B calls procedure C, VAX/VMS builds a call frame for procedure 
C. The call frame for procedure C is built on top of the call frame for 
procedure B. In other words, the call frame for the most recently called 
procedure is on the top of the stack. 

When a routine returns to its caller, the call frame for that routine is removed 
from the stack. Thus when procedure C finishes and control is returned to 
procedure B, the call frame for procedure C is removed from the stack. 

The SHOW CALLS command provides information about the sequence of 
currently active procedure calls or the number of call frames on the stack. For 
example, if your program contains a recursive routine, you can use a SHOW 
CALLS command to examine the chain of recursion. 
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The format of the SHOW CALLS command is 

SHOW CALLS [n] 

The optional parameter n specifies the call count, or the number of call frames 
to be displayed, by a decimal integer in the range 0 through 32,767. If you do 
not specify the parameter n, then information on all call frames is displayed. 
If the call count represented by n exceeds the current number of call frames, 
information on all call frames is displayed. If the call count is 0, the command 
is accepted but no information is displayed. Otherwise, the number of call 
frames specified by the parameter n is displayed. 

For each call frame, the debugger displays one line of information. The 
first line displayed contains information about the top call frame (the one 
representing the most recently called procedure); the next line contains 
information on the next most recently called procedure, and so on. 

Each line of information displayed by the debugger contains 

• The name of the module that contains the called routine. The debugger 
places an asterisk to the left of the module name if the module is set. 

• The name of the called routine. 

• The line number of the call (in line-oriented languages only). 

• The value of the PC in the calling routine at the time that control was 
transferred to the called routine. Note that this value is the location of 
the instruction following the call. The value of the PC is expressed in two 
ways: as an absolute virtual address and as a virtual address relative to 
the virtual address of the name of the routine. 

Note that even if your program contains no procedure calls, the debugger 
displays an active call when you issue the SHOW CALLS command. The 
reason for this is that your program has a stack frame built for it when it is 
first activated. 

Thus, if the debugger responds that there are no active calls when you issue 
a SHOW CALLS command, either your program has terminated or the stack 
has been corrupted. 

Example 3-8 demonstrates the use of the SHOW CALLS command. 


3.4 Related Qualifier Functions 

Many of the qualifiers that affect the SET BREAK, SET TRACE, SET STEP, 
SET WATCH, and STEP commands have the same functions. They can 
be divided into two broad categories: qualifiers that indicate location, and 
qualifiers that affect output. 
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Example 3-8 Using the SHOW CALLS Command 


DBOSTEP 

start at SUB2V/.LINE 15 
stepped to SUB2V/.LINE 16 

DBOSHOW CALLS !Display procedure calls. 


module name routine name line rel PC 


abs PC 


SUB2 SUB2 
♦SUB1 SUB1 
♦MAIN MAIN 


00000002 0000085A 

5 00000014 00000854 

10 0000002C 0000082C 


ISUB2 is the procedure that is 
!currently executing. SUB2 was 
!called by SUB1, and SUB1 was 
Icalled by MAIN. 

DBG>G0 

start at 19351 
‘/.DEBUG-1 -EXITSTATUS, 
completion* 


{Continue program execution, 
is ’7.SYSTEM-S-NORMAL, normal successful 


DBOSHOW CALLS 

•/.DEBUG-W-NOCALLS, no active call frames 

!Program has terminated. 


3.4.1 Qualifiers That Indicate Location 

This section describes a set of qualifiers that are common to SET BREAK, SET 
TRACE, and STEP. The qualifiers follow: 

/BRANCH 

/CALL 

/EXCEPTION 

/INSTRUCTION 

/INSTRUCTION=opcode 

/LINE 

/RETURN address 

When these qualifiers are used with the SET BREAK and SET TRACE 
commands, they tell the debugger where to break; and therefore take the 
place of an address expression. For example, the command SET BREAK 
/INSTRUCTION=ADDL3 breaks at every ADDL3 instruction. 

When these qualifiers are used with the STEP command, they tell the 
debugger where to step. For example, STEP/INSTRUCTION=ADDL3 tells 
the debugger to step to the next ADDL3 instruction. 

The seven qualifiers (or parameters) form a mutually exclusive set. For 
instance, if you issue the command SET STEP CALL but later issue the 
command SET STEP LINE, the LINE setting replaces the CALL setting as the 
default STEP condition. 
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3.4.2 Qualifiers That Affect Output 

This section describes another set of qualifiers that are common to the SET 
BREAK, SET TRACE, SET WATCH, and STEP commands. These qualifiers 
are: 


/SILENT 

/NOSILENT 

/SOURCE 

/NOSOURCE 

The /SILENT qualifier suppresses debugger output when the breakpoint, 
tracepoint, or watchpoint is taken. This feature is particularly useful with a 
DO clause on a SET BREAK, SET TRACE, or SET WATCH command. For 
example, you might set up a DO clause on a SET TRACE command to count 
the number of times your program accesses a given location. You can specify 
the /SILENT qualifier so you do not have to see the "trace at ... " message 
every time the tracepoint takes effect. 

DBG>DEFINE/VALUE C0UNT=0 

DBG>SET TRA/SIL '/.LINE 10 DO (DEF/VAL C0UNT=C0UNT+1) 

The /SOURCE qualifier controls whether you see the source code. If you 
issue the SET STEP SOURCE command, the debugger displays the source 
code at every step, breakpoint, tracepoint, and watchpoint. 

You can, however, override the default STEP setting by specifying a qualifier. 
For instance, if you want to see the source code at a particular breakpoint but 
the default setting is NOSOURCE, you can issue the command SET BREAK 
/SOURCE. 


3.5 Exit Handlers 


Exit handlers are procedures that are called whenever an image requests the 
$EXIT system service. A user program may declare one or more exit handlers. 
The debugger always declares its own exit handler. 

This section discusses the sequence in which exit handlers are executed and 
explains how to debug them. 


3.5.1 Sequence of Exit Handler Execution 

At program termination, exit handlers are executed in last-in/first-out order 
(LIFO); that is, the most recently declared exit handler is executed first, then 
the next most recently declared exit handler, and so on. 

The debugger exit handler is the first in and therefore the last out. 
Consequently, at program termination, the debugger exit handler executes 
after all user-declared exit handlers have executed. 
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3.5.2 Debugging Exit Handlers 

To debug an exit handler, you must first set a breakpoint in that exit handler. 
Then, you must cause that exit handler to execute either by including in your 
program an instruction that invokes the exit handler or by allowing your 
program to terminate. (At program termination, the system begins executing 
exit handlers in last-in/first-out order.) When the exit handler executes, the 
breakpoint will be activated and control returned to the debugger, which will 
display its prompt. You can then enter debugger commands. 


3.5.3 Identifying Exit Handlers 

The SHOW EXIT-HANDLERS command gives a display of the exit handlers 
that your program has declared. The exit handler routines are displayed in 
the order that they will be called (that is, last in, first out). The routine name 
is displayed symbolically, if possible. Otherwise its address is displayed. The 
debugger's exit handlers are not displayed. 

For example: 

DBG> SHOW EXITJHANDLERS 
exit handler at STACKS\CLEANUP 
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4 Symbol References and Their Interpretation 


In the context of debugging, symbols are strings of characters that represent 
files, program modules, routines, program locations, variables, arrays, or any 
other definable units. This chapter explains what you need to know about 
symbols to debug your program. 


4.1 Symbolic Debugging 

Symbolic debugging means debugging using symbols, instead of virtual 
addresses, to refer to memory locations. 

For the debugger to interpret symbols, information about them (in the form 
of symbol records) must be present in the executable image at run time. 

You control which symbol records are available at run time by using the 
/DEBUG command qualifier with the compile and LINK commands. 

By default, symbol records for traceback information are available at run time. 
Traceback information consists of symbol records that describe module names, 
routine names, and compiler-assigned line numbers. Traceback information is 
used both by the debugger and by the traceback utility. The traceback utility 
uses these symbol records to display the call stack when a program terminates 
abnormally. 

Example 4-9 shows a traceback display of the call stack. 

Example 4-9 Traceback Information 


7.PAS-F-ERRACCFIL, error in accessing file PAS$OUTPUT 
7.P AS - F - ERRQPECRE, error opening/creating file 
7.RMS-F-FNM, error in file name 
7.TRACE-F-TRACEBACK, symbolic stack dump follows 


module name 

routine name 

line 

rel PC 

abs PC 

PAS$IO_BASIC 

_PAS$CODE 


00000192 

0000ICED 

PAS$IO_BASIC 

_PAS$C0DE 


0000054D 

000020A8 

PAS$IO_BASIC 

_PAS$CODE 


0000028B 

00001DE6 

EIGHTQUEENS 

EIGHTQUEENS 

59 

00000020 

000005A1 


To prevent the inclusion of symbol records for traceback information in the 
executable image, you can specify /NODEBUG with the compile command 
or /NOTRACEBACK with the LINK command. Note however that specifying 
/NOTRACEBACK also disables the debugger. In general, if you intend 
to debug your program, you want to include traceback information in the 
executable image. On the other hand, when your program is fully debugged, 
you might want to prevent the inclusion of traceback information in the 
executable image in order to reduce the size of the executable image file. 

Sections 4.2.1 and 4.2.2 describe how to use the /DEBUG command qualifier 
to include symbol records in the executable image. Section 4.2 describes the 
symbol tables that contain these records. 
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However, even if the required symbol records are present in the executable 
image at run time, the debugger will be able to access them only if they are 
present in its run-time symbol table (RST). To put symbol records in the RST, 
you use the SET MODULE command. Section 4.5.2 describes how to use 
these commands. 

Finally, given that the required symbol records are present in the RST, it 
might also be necessary to specify the program region (or scope) in which a 
particular symbol is to be interpreted. For example, symbols with the same 
name, but with declarations in different routines, must be differentiated from 
one another. In this case, you must prefix the symbol name with a path name 
or use the SET SCOPE command to define the scope. Section 4.4 discusses 
these topics. 


4.2 Symbol Tables Used by the Debugger 

Symbol tables contain symbol records that the debugger uses to associate a 
symbol with a program location (that is, a virtual address). In addition, by 
means of some symbol records, the debugger can associate attributes with a 
program location, such as the length of that location and its data type. 

The debugger uses the following three symbol tables, which are described in 
the following sections. 


4.2.1 Debug Symbol Table 

When the linker creates an executable image, it creates a debug symbol table 
(DST) unless you specify the /NOTRACEBACK qualifier with the LINK 
command. The linker includes the DST in the executable image. 

If you specify the /DEBUG qualifier with the LINK command, the linker 
includes in the DST all symbol records that are present in the object 
module(s) from which it creates the executable image. Thus, if symbol 
records for local symbols are present in the object module(s) (because you 
specified /DEBUG at compile time), the DST will contain symbol records for 
local symbols and for traceback information. 

If you do not specify the /DEBUG qualifier with the LINK command, the 
linker includes only symbol records for traceback information. Thus, even if 
symbol records for local symbols are present in the object module(s), they are 
not included in the executable image. 

A DST symbol record typically contains the name of a symbol, its type, its 
length, and its value or address. The type information may simply mark the 
symbol as a routine or a label, or it may define a more or less complex data 
type. Similarly, the address information may be a simple virtual address or 
value, or it may specify a more or less complex way of computing the symbol 
address. 

At run time, the debugger uses the symbol records in the DST to build the 
run-time symbol table (RST). For more information on the RST, refer to 
Section 4.2.3. 
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4.2.2 Global Symbol Table 

When the linker creates an executable image, it creates a global symbol 
table (GST). The linker includes the GST in the executable image only if the 
/DEBUG qualifier is specified with the LINK command. 

The linker creates the GST from its own internal symbol table. As a result, 
symbol records in the GST contain no more information than the linker needs 
to do its job. Symbol records in the GST describe all global symbols in the 
image, such as routine names, procedure entry points, and global data names. 
Symbol records for these global symbols associate symbol names with virtual 
addresses or values, but they do not contain information about data types. 
See the description of the VAX/VMS Linker in the VAX/VMS Linker Reference 
Manual for information on the content and format of these symbol records. 

The debugger uses the GST only if it cannot locate needed information in 
the DST. If a symbol is represented in both the DST and the GST, the DST 
symbol record usually contains more information about the symbol than the 
GST symbol record. 


4.2.3 Run-Time Symbol Table 

When the debugger is activated at run time, it uses available symbol records 
in the DST and GST to generate symbol entries for the run-time symbol table 
(RST). 

The RST allows the debugger random access to symbols during a debugging 
session. Its purpose is to allow efficient access to symbol records contained in 
the DST and GST. Whenever you mention a symbol in a debugger command, 
the debugger checks the RST for the information it needs to interpret that 
symbol. If there is no entry for a symbol in the RST, you cannot access that 
symbol. 

When the debugger is initialized at run time, it allocates enough memory 
to allow the RST to contain symbol records for the six largest modules in 
the program, approximately. However, VAX/VMS does not allow memory 
allocation for the RST if such allocation causes the process to exceed its virtual 
address quota as established by system parameters. 

At debugger start up, symbol records for all modules are not automatically 
included in the RST. Instead, if the debugger is activated by the RUN 
command, symbol records for the module containing the transfer address are 
included in the RST. If the debugger is activated by the DEBUG command, 
symbol records for the module containing the current PC are included in the 
RST. 

Symbol records for all other modules are included in the RST by setting the 
module. Module setting is the process by which all the symbol records of a 
particular module are included in the RST. Module setting makes the symbols 
of a module accessible to debugger commands and is accomplished in two 
ways: automatically, by using dynamic module setting; and manually by 
using the SET MODULE command. 

Dynamic module setting is initially enabled by default when you invoke 
the debugger. In dynamic module setting, the debugger sets certain modules 
automatically for you: whenever the debugger prompt is displayed (whenever 
the debugger interrupts execution), the debugger automatically sets the 
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module enclosing the PC location and issues an informational message. If the 
module is already set, dynamic module setting has no effect. For example, 
suppose you are at a call of routine SUBR and decide to step into SUBR: 

DBG> STEP/INTO 

stepped to routine SUBR 
%DEBUG-I-DYNMODSET, setting module SUBR 

Dynamic module setting, by setting the module surrounding the current 
PC location, makes all the symbols of that module accessible to debugger 
commands. 

If you want to set a module that has not been set dynamically (to access 
symbols declared in arbitrary modules) you need to use the SET MODULE 
command. For example: 

DBG> EXAMINE X 

y,DEBUG-W- NOSYMBOL, symbol ’X’ is not in the symbol table 
DBG> SET MODULE SWAP 
DBG> EXAMINE X 
SWAP\X: 17 

Symbol records can be removed from the RST by means of the CANCEL 
MODULE command; removing symbol records from one or more modules 
makes room in the RST for the symbol records of other modules. 

Note that dynamic module setting makes the debugger easier to use; 
however, it may slow the debugger down as more and more modules are 
set. The debugger does not cancel modules for you. If performance becomes 
a problem, you can use the CANCEL MODULE command selectively, 
or you can turn off dynamic module setting by issuing the SET MODE 
NODYNAMIC command. You can reenable dynamic module setting with the 
SET MODE DYNAMIC command. 

If the debugger cannot find the information it needs to interpret a symbol, 
one of the following conditions exists: 

• The symbol reference is incorrect. In this case, you can check the symbol 
reference for spelling and syntax errors, and then correct them. 

• The symbol refers to more than one entity. In this case, you can make 
the symbol reference unique by specifying the symbol with a path-name 
prefix or by using the SET SCOPE command. 

• Symbol records for the module containing that symbol are not present 
in the RST. In this case, you can issue the SET MODULE command to 
include the symbol records for that module. 

• Symbol records for the symbol are not present in the executable image. 

In this case, you will not be able to use the symbol during the debugging 
session. To use the symbol, you will have to compile, link, and run the 
program again, taking care to specify the /DEBUG command qualifier. 
See Sections 4.2.1 and 4.2.2 for information on using the /DEBUG 
command qualifier. 
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4.3 Kinds of Symbols 

Symbols differ from one another not only in what they represent but also in 

the contexts in which they can be interpreted. 

This section describes 

• Symbols that can always be interpreted in a debugging session 

• Symbols that can be interpreted in a debugging session if you define them 
during the session 

• Symbols whose interpretation depends on many factors, such as whether 
the /DEBUG qualifier was specified at compile time and which modules' 
symbols are in the RST 


4.3.1 Debugger Permanent Symbols 

Debugger permanent symbols are symbols that are known to the debugger in 
any debugging context. Thus, you can use them at any time in a debugging 
session. The following are the debugger permanent symbols and their 
referents: 

• The characters %R followed by a numeral from 0 through 11 represent 
the corresponding VAX general purpose registers, such as %R0, %R1, 
%R2, %R3, %R4, %R5, . . . %R11. In general, these symbols are 
debugger permanent symbols. 

• %PC represents the program counter and is a debugger permanent 
symbol. 

• %PSL represents the processor status longword and is a debugger 
permanent symbol. 

• %SP represents the stack pointer and is a debugger permanent symbol. 

• %AP represents the argument pointer and is a debugger permanent 
symbol. 

• %FP represents the frame pointer and is a debugger permanent symbol. 

• The period represents the current entity; you can also use %CURLOC. 
You may use them to refer to the program location last referenced 
by an EXAMINE or DEPOSIT command. See Section 5.2.6 for more 
information. 

• The circumflex (*) represents the logical predecessor of the current entity; 
you can also use %PREVLOC. 

• The backslash (\) represents the value last displayed by an EVALUATE, 
EXAMINE, or DEPOSIT command; you can also use %CURVAL. 

• <RET> represents the next location; you can also use %NEXTLOC. 

You can use %CURLOC, %PREVLOC, %CURVAL, and %NEXTLOC when 
you cannot use the symbols they represent because the symbols would 
be ambiguous or because you cannot use <RET> in the middle of an 
expression. 
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You may leave out the percent sign in a reference to a register (for example, 
abbreviate %R0 as RO). However, if you do not use the percent sign, the 
debugger may interpret these symbols as program variables you have defined, 
not as debugger permanent symbols. The debugger interprets these symbols 
as debugger permanent symbols only if your program does not contain 
variables of the same names. 


4.3.2 Symbols Created by the DEFINE Command 

During a debugging session, you can use the DEFINE command to create a 
new symbol or to change the value of a currently existing symbol. 

For example, if you find yourself frequently referencing a difficult-to- 
remember, nonsymbolic program location, you can define a symbol to 
represent that program location. Then, for the remainder of the debugging 
session, you can refer to that program location by the symbol that represents 
it. 

Symbols created with the DEFINE command are deleted when you end the 
debugging session. 

As a result of the following command, MINI may be specified during a 
debugging session instead of PROGRAM\ROUTINEA\BLOCKB\MINIM+20: 

DBODEFINE MINI = PR0GRAM\R0UTINEA\BL0CKB\MINIM+2O 

See the Command Dictionary for a full description of the DEFINE command. 


4.3.3 Program Symbols 

Program symbols (also called identifiers) are the symbols you use when you 
write your program. 

A program symbol is interpreted according to how and where it is declared 
and where it is used. 

A declaration of a symbol specifies attributes permanently associated with the 
symbol, such as the data type, how much storage is allocated, and so on. The 
symbol is interpreted by means of these attributes. 

Program symbols fall into one of two categories: 

• Data names, which identify data operated on by the program's executable 
statements 

• Program unit labels and program location labels, which identify or name 
programs, procedures, lines, or statements 

The following sections discuss the syntactic and semantic differences among 
program symbols. Syntactically speaking, symbols range from simple 
characters or names to complex entities composed of several names separated 
by various delimiting characters. 

The following subsections present the basic types of program symbols in 
order to demonstrate the debugger's capacity to interpret the full range of 
language-specific symbol syntax. 
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For those readers who are already familiar with the varieties of program 
symbols, it may be enough to know that the debugger interprets program 
symbols in the source-language syntax. Thus, in general, if a symbol is legal 
in the source language, the debugger is capable of interpreting it. 


4.3.3.1 Simple Symbols 

The debugger interprets simple symbols according to the syntactic rules of the 
source language. 

A simple symbol is a program symbol that does not contain symbolic prefixes 
or suffixes that further qualify the data item represented by the symbol. 

A simple symbol may refer to an individual data item or to an entire range of 
data items. 

A simple symbol may be a data name that represents, for example, a numeric 
constant (X), an array (ARR), or a character string (A5$). 

If a symbol is legal in the source language, the debugger is generally able 
to interpret it. For example, if language is set to VAX BASIC, the debugger 
interprets the symbol T$ as a legal symbol representing a character string. 

However, in some languages, symbol names may exist that are not considered 
identifiers in the syntax of the currently set language. For instance, in 
COBOL, sections and paragraphs can have numeric names such as "12." 

In BLISS, the compiler generates names of the form "P.xxx" for PLITs, even 
though the period is not a valid character in BLISS identifiers. 

The %NAME built-in symbol causes the debugger to interpret its argument as 
a name, whether or not it appears to be a name. It has either of the following 
forms: 

•/.NAME id-char-string 
•/.NAME ’any-char-string’ 

The quotes are only needed for one of the following reasons: 

• If the name has a semicolon (;) (which would ordinarily terminate the 
command) 

• If the name has lower-case alphabetics (which would ordinarily be 
uppercased) 

Examples follow: 

DBG> SET BREAK ‘/.NAME 12 
DBG> EXAMINE ‘/.NAME ’P.AAA’ 


4.3.3.2 Subscript-Qualified Symbols 

The debugger interprets subscript-qualified (or subscripted) symbols in the 
source language syntax. 

A subscripted symbol is a symbol used to refer to a data item in an array. 

Because an array consists of an ordered set of data items, you can identify an 
array item by specifying the array name and the item's position in the array. 
The position of an array item is indicated by one or more subscripts. For 
example, (1+2) is a valid subscript in the subscripted symbol ARR(I+2). 
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The syntax of the subscripted symbol depends on the language that is 
currently set. If, for instance, you want to examine the first item in the 
array ARR and the currently set language is FORTRAN, you would give 
the command EXAMINE ARR(l). However, a similar command in PASCAL 
would look like this: EXAMINE ARR[1]. 

The number of subscripts used to identify a data item in an array indicates 
the dimensions of the array. Thus, the third member of a one-dimensional 
array named ARR is identified by the subscripted symbol ARR(3), and the 
array member located in the third row, second column of a two-dimensional 
array named TAB is identified by the subscripted symbol TAB(3,2). 

You can, however, specify or examine an array slice instead of only one item 
in the array. This capability allows you to see the items in the array as a 
whole. You specify array slices much the same way you specify ordinary 
subscripted symbols. For example, the symbol ARR(1,2:4,6) is a valid 
FORTRAN array slice. It would produce an array slice made up of the 
items ARR(1,4), ARR(1,5), ARR(1,6), ARR(2,4), ARR(2,5), and ARR(2,6). 

In effect, an array slice is simply an array that is a subset of the parent array. 


4.3.3.3 Structure-Qualified Symbols 

The debugger interprets symbols that identify members of data aggregates 
according to the syntactic rules of the source language. 

A data aggregate that consists of data items of different types is called a data 
structure or a record. Records contain data items that may contain subitems 
that may contain sub-subitems, and so on. 

For example, the following display is a declaration, in VAX PASCAL, of a 
record Person: 

TYPE PERSON = RECORD 

NAME : PACKED ARRAY[1..20] OF CHAR; 

AGE : INTEGER; 

SEX : (MALE,FEMALE); 

SALARY : INTEGER 
END; 

VAR COURTNEY : PERSON; 

In most languages, to reference a field in a record, you must use a structure- 
qualified symbol containing the name of the desired field and the names of 
all other fields that contain that field. 

For example, if you wanted to reference the field Age in the record above, 
you would use the structure-qualified symbol COURTNEY.AGE. 

The period is a delimiter used to separate field and record names. 

Note that in those languages that permit the nesting of arrays and records, 
symbolic references to fields within those records are a combination of 
subscripted symbol and structure-qualified symbol. 

Generally, a legal symbol in the source language is capable of being 
interpretated by the debugger. 

You can also specify or examine an entire aggregate, which means all the 
items that make up the aggregate. You do not have to specify each of the 
items individually. The aggregate output from a record shows the name and 
value of each item in the record. Similarly, the aggregate output from an 
array shows the subscript and value of each array item. 
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4.3.3.4 Pointer-Qualified Symbols 

Some languages use pointer-qualified symbols to reference data items that 
are not bound by the compiler to specific memory addresses. As with other 
source-language symbols, the debugger interprets pointer-qualified symbols 
in the syntax of the source language. 

For example, to indicate a pointer type in VAX PASCAL, you specify the 
name of the base type preceded by a circumflex (~). Thus, if the record 
PERSON in Section 4.3.3.3 is the base type, the pointer variable P is declared 
as 

VAR P : ^PERSON; 

To access the entire record, the pointer-qualified symbol P* is used. 

To access a field within the record, include the name of the field, as shown 
below. 

P~ .SALARY 


4.4 Symbol Resolution in the Source Language 

The recognition or resolution of a symbol during a debugging session depends 
on the resolution of the symbol in the source language and on the debugger 
context in which the symbol is mentioned. 

This section discusses the factors that influence the resolution of a symbol 
within the source language. These factors are the context in which the 
symbol declaration occurs and the presence or absence of a global attribute in 
the symbol declaration. 


4.4.1 Program Context of Symbol Declarations 

Typically, programs contain symbol declarations. A symbol declaration 
associates a symbol to an entity and associates with that entity certain 
properties (such as type or storage allocation). Declarations may be implicit; 
however, this discussion does not distinguish between implicit and explicit 
declarations. 

The scope of a declaration is the set of program locations wherein the symbol 
is interpreted as representing the entity bound to it in that declaration. 

The same symbol may be declared more than once. Declarations of the same 
symbol have disjoint or nonoverlapping scopes, and each declaration binds 
the symbol to a different entity (unless the symbol is global). 

If a declaration occurs in a program unit that does not contain other program 
units, the scope of the declaration is the program unit in which it occurs. If 
a declaration occurs in a program unit that contains other (nested) program 
units, the scope of the declaration is the program unit in which the declaration 
occurs and all other nested program units that do not themselves contain 
declarations of the same symbol. 

Figure 4-2 shows nested program units containing several symbol 
declarations. The symbol X is declared in two program units. The scope 
of X declared in A is A, B, and D, but not C, because X is redeclared in C. 
The scope of X declared in C is C; the scope of Y is B and C; and the scope of 
Z is D. 
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Figure 4-2 Scope of Symbol Declarations 


A: 


DECLARE X 



D: 


DECLARE Z 


ZK-011-81 


4.4.2 Global Symbols 

A global symbol is a symbol whose declaration contains a global attribute. 

The presence or absence of a global attribute in a declaration influences the 
resolution of that symbol. 

Global symbols make possible references to the same entity by program units 
that do not contain one another (nonnested program units). To accomplish 
this, each program unit declares the symbol with the global attribute, though 
not necessarily with all other attributes identical. 

Thus, a global symbol is bound by several declarations to the same entity. 
This contrasts with multiple declarations of the same local (or nonglobal) 
symbol where each declaration associates the symbol with a different entity. 

Strictly speaking, the scope of the declaration of a global symbol is no 
different from the scope of the declaration of a nonglobal symbol; however, 
the entity referred to by that symbol may be capable of interpretation outside 
of the scope of its declaration in any one program unit, namely, in those other 
program units that also declare it. 

Figure 4-3 depicts declarations of global symbol X in two nonnested program 
units. Both program units also make references to X. Because X is declared 
with the global attribute in both program units, references to X in either 
program unit are references to an identical memory location, the entity 
represented by X. 
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4.5 


Figure 4-3 Global Symbol X 


PROGRAM 

UNIT 

A 


PROGRAM 

UNIT 

B 


DECLARE X GLOBAL 

... X ... 


... X ... 







DECLARE X GLOBAL 

... X ... 
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Symbol Resolution in the Debugger 

As described in Section 4.4.1, a symbol in the source language is interpreted 
as representing the entity associated with it in that declaration within whose 
scope the symbol occurs. 

In debugging, however, wherein random access to symbols anywhere in 
the program may be necessary, you use path names to distinguish multiple 
declarations of the same symbol. 

A path name consists of one or more program location labels that serve to 
specify a program location or range of program locations. Hence, a path name 
is used to "locate" a symbol within the scope of the declaration that binds it 
to the entity you want to reference. Of course, the program location(s) 
indicated by the path name must be within the scope of some declaration of 
the symbol; otherwise the symbol cannot be interpreted at all. 

Thus, when you are debugging a program containing multiple declarations of 
the same symbol and you want to indicate to the debugger that you wish the 
symbol to be interpreted as representing one of several possible entities, you 
simply specify a path name with the symbol. The debugger then interprets 
the symbol as representing the entity associated with it in the declaration 
whose scope includes the program location(s) denoted by the path name. 

If you specify a path name as a parameter in the SET SCOPE command, you 
are in effect establishing that path name as a default path-name prefix, to be 
used in all symbol references that do not already contain a path-name prefix. 
See Section 4.5.3 for more information on the SET SCOPE command. 
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You may specify as many path-name parameters as you like in the SET 
SCOPE command; the debugger attempts to interpret the symbol using 
the first path name listed. If that fails, the debugger uses the second path 
name and continues in this manner until it finds a path name that identifies 
a program location within the scope of a declaration of the symbol. The 
debugger then interprets the symbol as representing the entity identified in 
the declaration. 

If you do not specify a path-name prefix when you use a symbol in a 
debugger command and you have not specified default path names using 
the SET SCOPE command, the debugger looks up a symbol according to 
the following default scope. By default, the debugger looks up a symbol 
according to the scope search list 0,2,2, . . . ,N, where N is the number of 
calls in the call stack. This scope search list is based on your current PC and 
changes dynamically as your program executes. The default scope means that 
a symbol lookup such as "EXAMINE X" first looks for X in the routine that is 
currently executing (scope 0); if no X is visible there, the debugger looks in 
the caller of that routine (scope 1), and so on down the call stack; if X is not 
found in scope N, the debugger searches the rest of the run-time symbol table 
(RST), then searches the global symbol table (GST), if necessary. 

When you use a symbol X in a debugger command, you may or may not use 
a path-name prefix. If you use a path-name prefix, the debugger interprets X 
as if it appeared in the program location(s) defined by that path name. The 
debugger issues an error message if there is no declaration of X whose scope 
includes the program location(s) defined by the path name. If you do not use 
a path-name prefix, the debugger attempts to interpret X using default path 
name(s), either (1) path name(s) you specified in the SET SCOPE command, 
or (2) if you have not specified a path name, the path name indicated by the 
program location containing the current PC. 

For example, assume you enter the following commands: 

DBG>SET SCOPE A\B,C 
DBOEXAMINE X 

You have not specified a path-name prefix in the EXAMINE command. 
Consequently, the debugger uses A\B\ as a path-name prefix and attempts to 
locate a declaration of X whose scope includes the program location identified 
by the path name A\B\. If the debugger finds such a declaration of X, it uses 
that declaration to interpret X in the EXAMINE command. If it does not find 
such a declaration of X, the debugger then repeats the procedure using C\ as 
a path-name prefix. 

If the debugger fails to find a declaration of X whose scope includes the 
program locations identified by the default path names, it searches the 
entire run-time symbol table (RST) for a declaration of X. If the debugger 
locates one, it resolves X using that declaration. If it locates more than one 
declaration of X, it issues an error message to the effect that an ambiguous 
reference has been made. 

If the debugger does not find a declaration of X in the RST, it searches the 
global symbol table (GST). If the debugger does not find a declaration of X in 
the GST, it displays a message indicating that the symbol could not be found. 
See Section 4.2.3 for information on what to do. 

To utilize fully the debugger's capacity for distinguishing among multiple 
declarations of the same symbol, you must be thoroughly familiar with how 
path names are specified. 
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4.5.1 Specifying Path names 

A path name is a string of program location labels that identifies a program 
location or a range of program locations. A path name is used in two 
contexts: 

• As a prefix to a symbol in a debugger command 

• As a parameter in the SET SCOPE command 

The labels in a path name are strung together so that each label designates 
a program unit that contains the program unit designated by any label to its 
right. Thus, if PROG is a label appearing in a path name, labels to the left 
designate "containing" program units, and the labels to the right designate 
"contained" program units. 

The backslash character (\) is used both to separate path-name elements from 
one another and to separate the entire path name from the symbol to which it 
is prefixed. Note that if the path name is specified as a parameter in the SET 
SCOPE command, it is not followed by a symbol; therefore, the rightmost 
path-name element in the path name is not followed by a backslash. On the 
other hand, if the same path name is used to prefix a particular symbol in 
a command, the rightmost path-name element is followed by a backslash to 
separate it from the symbol. 

The kinds of labels used in a path name vary somewhat from language to 
language; however, in general, a path name always includes a module name 
and usually includes one or more of the following elements: 

• Routine name(s) 

• Block name(s) 

• Invocation number 

• Line number 

• Numeric label 

A routine is a separately invocable program unit, that is, a program unit that 
may be activated by a call. A block is a program unit that is activated in 
normal execution sequence (inline); it is not separately in vocable. A routine 
may contain one or more blocks and routines. A block may contain one or 
more routines and blocks; that is, there may be nesting of blocks and routines. 


The following is a typical path name consisting of module, block, and routine 
names: 

INV\PARTS\AUTO\ 

In languages that use line numbers, the %LINE path-name element specifies 
the source-code line. The following is a path name that uses the %LINE 
element: 

MEDIANV/.LINE 330\ 

In languages that allow recursion, an invocation number is used in a path 
name to distinquish among multiple invocations of the same program unit 
(and therefore among multiple generations of symbols). An invocation 
number is always associated with a routine name, never a block name; one or 
more spaces must separate a routine name from an invocation number. (See 
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Section 4.5.1.2 on invocation numbers for more information.) The following 
is a path name that specifies an invocation number: 

M0D\R0UT 1\BLK\ 

Figure 4-4 shows a program containing nested routines and blocks with 
declarations of the symbol X. Examples 1 through 4 refer to Figure 4-4. 

In these examples, path names are used as prefixes of the symbol X in the 
EXAMINE command and as parameters in the SET SCOPE command. 

Figure 4-4 Path Names and Scope 



4.5.1.1 Path Name Examples 

This section contains four examples of path names. 

dbg>examine a\x 

The path-name prefix A\ identifies the range of program locations defined 
by the program unit A. The debugger attempts to locate a declaration of 
X whose scope includes A. Since such a declaration of X appears in A, the 
debugger interprets X as representing the entity declared in A. The debugger 
then examines the value of X. 

The scope of the declaration of X in A consists both of those locations in A 
that are not also in other blocks and of B. C and the unnamed (anonymous) 
block are not in the scope of the declaration of X in A because they also 
contain declarations of X. 

DBG> EXAMINE A\B\C\X 
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The path-name prefix A\B\C\ identifies program unit C. The debugger 
searches for a declaration of X whose scope includes C. It finds such a 
declaration in C and interprets X as representing the entity declared in C. The 
debugger then examines the value of X. 

Remember that a symbol redeclared in a contained program unit is interpreted 
according to the declaration in that unit, not the declaration in the outer unit. 
Thus, the symbol X in C has a different meaning (as declared) than the 
symbol X that is declared in A. 

DBG>EXAMINE AV/.LINE 110\X 

The path name A\%LINE 110\ identifies a program location within the 
anonymous block because line number 110 is contained in the anonymous 
block. 

The debugger searches for a declaration of X whose scope includes line 
number 110. It finds such a declaration in the anonymous block and 
interprets X as representing the entity declared therein. The debugger then 
examines the value of X. 

Note that only by means of the %LINE path-name element is it possible to 
identify program locations in an anonymous block. Thus, in this example, 
without using the %LINE path-name element, it would be impossible to 
reference the entity represented by X as declared in the anonymous block. 

DBG>SET SCOPE A\B 
DBG>EXAMINE X 

Since no path-name prefix is used in the EXAMINE command, the default 
path-name prefix A\B\ is attached to X. The debugger searches for a 
declaration of X whose scope includes B, the range of locations specified 
by A\B\. It locates such a declaration in A and interprets X as representing 
the entity declared in A. The debugger then examines the value of X. 


4.5.1.2 Path Name Completion 

In programs where deep nesting of program units occurs, the naming of 
every containing program unit in a path name can be burdensome. To make 
it easier for you to specify path names, the debugger supports path name 
completion. 

A complete path name is a path name that mentions every path-name 
element: all routines and blocks, as well as label and line numbers, if 
applicable. An incomplete or abbreviated path name is a path name that 
does not mention every path-name element in the specification. 

When the debugger encounters a path name, it first determines whether the 
path name is complete or incomplete. If it is complete, the debugger uses the 
path name to resolve the symbol reference. If it is incomplete, the debugger 
determines whether it is an abbreviation for a complete path name and, if so, 
whether it is an unambiguous abbreviation. 

An incomplete path name is an abbreviation for a complete path name if 

• The path-name elements in the incomplete path name appear in the 
complete path name in the same order. 

• The rightmost element in the complete path name is the rightmost 
element in the incomplete path name. 
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For example, the incomplete path name 

RUGV/.LINE 784\ 

is an abbreviation for the complete path name 

MAT\CLR1\RUG\%LINE 784\ 

because (1) RUG\ and %LINE 784\ in the incomplete path name are in the 
same order as in the complete path name and (2) the rightmost element 
%LINE 784\ in the complete path name is the rightmost element in the 
incomplete path name. 

The abbreviated path name is unambiguous if there is not more than one 
complete path name for which it is an abbreviation. 

For example, let us assume that two different subroutines, both named 
SUB, are declared in program units PROG and QUAR, respectively. The 
incomplete path name SUB is ambiguous because there are two complete 
path names, PROG\SUB and QUAR\SUB, for which it is an abbreviation. 

An incomplete path name is acceptable to the debugger so long as it is an 
abbreviation (according to the definition above) for one (and not more than 
one) complete path name. 

Unique symbols can always be specified without path-name qualification. 

Global symbols may be specified by preceding the symbol with a backslash 
(\). For example, \X indicates that X is a global symbol. 


4.5.1.3 Invocation Numbers 

Routines are separately invocable program units; that is, they are activated 
by calls, rather than by inline execution. Thus during the execution of a 
program, there may be several simultaneous invocations of a routine or none 
at all. 

If a symbol representing a dynamic entity is declared in a routine or in a block 
within a routine, the entity represented by that symbol is generated anew 
each time the routine is invoked. For each invocation of the routine, there 
is a corresponding generation of the entity. Invocation numbers are used 
in path names to denote particular routine invocations (and thus particular 
generations of an entity). 

Invocation numbers are nonnegative decimal integers inserted in the path 
name following the name of the rightmost routine in the complete path name. 
The number zero (0) denotes the most recent invocation of the innermost 
(most deeply nested) routine; the number one (1) denotes the invocation 
before that; and so on. 

For example, if a module MOD contains a routine ROUT that contains a block 
BLK, then the path name that identifies the generation of BLK that resulted 
from the most recent invocation of ROUT is 

MODXROUT 0\BLK 

The path name that identifies the generation of BLK that resulted from the 
previous invocation of ROUT is 

MOD\ROUT 1\BLK 
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Every complete path name that contains the name of a separately invocable 
entity has an invocation number. When an invocation number is not present 
in a path name that contains the name of a routine, the debugger implicitly 
assumes the most recent invocation of the routine and supplies the default 
invocation value zero (0). 

Every path name containing the name of more than one routine specifies an 
invocation of the innermost routine. In a path name, invocation numbers 
cannot be associated with a routine name that appears to the left of another 
routine name. 

How you use a path name with an invocation number to specify a particular 
generation of a dynamic entity depends on the relative positions of the 
innermost routine and the program unit containing the declaration of the 
entity. The symbol bound to the dynamic entity you want to reference may 
be declared in any of the following: 

• The innermost routine 

• A block contained in the innermost routine 

• A program unit that contains the innermost routine 

These three possibilities give rise to the three program situations illustrated in 
Figures 4-5, 4-6, and 4-7. 

Figure 4-5 Symbol Declaration in the Innermost Routine 


INNERMOST ROUTINE 


DECLARE X 


LOCATION(S) 
IDENTIFIED 
BY PATHNAME 


ZK-014-81 


If the symbol is declared in the innermost routine, the debugger references 
the generation of the entity corresponding to the invocation of the routine (if 
there is one) denoted by the path name. Figure 4-6 illustrates this program 
situation. 
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Figure 4-6 Symbol Declaration in a Contained Block 


INNERMOST ROUTINE 


BLOCK 


DECLARE X 


LOCATION(S) 
IDENTIFIED BY 
PATHNAME 



ZK-015-81 



If the symbol is declared in a block contained in the innermost routine and if 
program execution has reached that block, then the debugger references the 
generation of the entity corresponding to that block activation. 

However, if program execution has not reached the block containing the 
declaration (as would be the case, for example, if you set a breakpoint at a 
location in the routine before the location that marks the beginning of the 
block), then the generation of the symbol specified by the path name does 
not exist, and the debugger issues an error message to that effect. Figure 4-7 
illustrates this program situation. 
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Figure 4-7 Symbol Declaration in a Containing Program Unit 


PROGRAM UNIT 

DECLARE X 


INNERMOST ROUTINE 


LOCATION(S) 
IDENTIFIED BY 
PATHNAME 


ZK-016-81 


Some invocation of a program unit provides the context for the invocation of 
the innermost routine denoted by the path name. The debugger references 
the generation of the entity corresponding to that invocation of the program 
unit. Figure 4-7 illustrates this program situation. 

Note that when you specify an invocation number, you must leave one or 
more spaces or tabs between it and the separately invocable routine. 


4.5.2 The SET, SHOW, and CANCEL MODULE Commands 

The SHOW MODULE command displays the following information about 
one or more modules in your program: 

• The module name 

• The presence (or absence) of symbol records for that module in the RST 

• The language in which the module is written 

• The approximate space (in bytes) required in the RST for symbols in that 
module 

• The total number of modules selected for display 

• The number of unused bytes in the space allocated for the RST 

The SHOW MODULE command has the following format: 

SHOW MODULE [/SHARE] [module-name [_]] 

The /SHARE qualifier controls whether the debugger includes, in the SHOW 
MODULE display, any shareable images that have been linked with your 
program but are external to your program. These shareable images are 
primarily Run-Time Library images, but they also include any shareable 
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images called by your program. By default (/NOSHARE), no shareable 
images are selected for display. 

To insert symbol records for one, several, or all modules in the RST, you use 
the SET MODULE command. It has the following format: 

SET MODULE [/qualifier] [module-name [,module-name...]] 

To include symbol records for one or several modules, specify the module 
name(s) in the SET MODULE command. In this case, do not specify a 
command qualifier. 

To include symbol records for all modules, specify the /ALL command 
qualifier in the SET MODULE command. In this case, do not specify a 
module name or names. 

Note that if a parameter in the SET SCOPE command designates a program 
location in a module whose symbol records are not already in the RST, the 
debugger copies symbol records of that module into the RST when the SET 
SCOPE command is executed. 

When all the memory space allocated for the RST is occupied by symbol 
records and you want to include additional symbol records, you have 
two alternatives. You can either allocate more memory with either the 
ALLOCATE or the SET MODULE/ALLOC ATE command, or you must issue 
the CANCEL MODULE command in the following format: 

CANCEL MODULE [/qualifier] [module-name [.module-name...]] 

To delete symbol records of one or several modules, specify the module name 
or names in the CANCEL MODULE command. In this case, do not specify a 
command qualifier. 

To delete symbol records of all modules, specify the /ALL command qualifier 
in the CANCEL MODULE command. In this case, do not specify a module 
name or names. 

Example 4-10 demonstrates the SHOW, SET, and CANCEL MODULE 
commands. 


4.5.3 The SET, SHOW, and CANCEL SCOPE Commands 

The purpose of the SET SCOPE command is to indicate one or more path¬ 
name prefixes to be used in the interpretation of symbols without path-name 
prefixes. 

The numbers 0, 1, 2, and so on, which appear in path names as invocation 
numbers, may also be used as parameters in the SET SCOPE command. Used 
in this way, these numbers are numeric path names. 

The numeric path name 0 specifies that symbols without path-name prefixes 
are to be interpreted as if they appeared in the currently active routine; 
numeric path name 1, in the program unit that contains the call to the 
currently active routine; numeric path name 2, in the program unit that 
contains the call to the program unit that contains the call to the currently 
active routine; and so on. 

If you do not issue a SET SCOPE command, the debugger exhibits a default 
behavior equivalent to the following SET SCOPE command (here, n is the 
number of calls in the call stack): 

SET SCOPE 0,1,2, .. . n 
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Example 4-10 Using the SET/SHOW/CANCEL MODULE 
Commands 


VAX-11 DEBUG Version 3.0-3 


'/.DEBUG-1-INITIAL, 

, language 

is BASIC, 

module set to "MEANSUB$MAIN 

dbg>show MODULE 

module name 

symbols 

language 

size 

BAS$MSGDEF 

no 

BLISS 

68 

BAS$ST0P 

no 

BLISS 

284 

MEANSUB$MAIN 

yes 

BASIC 

172 

0TS$LINKAGE 

no 

MACRO 

176 

total modules: 4. 

dbg>set MODULE otsilinkage 

remaining size: 60784. 

DBG>SH0W MODULE 

module name 

symbols 

language 

size 

BASIMSGDEF 

no 

BLISS 

68 

BAS$ST0P 

no 

BLISS 

284 

MEANSUB$MAIN 

yes 

BASIC 

172 

OTS$LINKAGE 

yes 

MACRO 

100 


total modules: 4. remaining size: 60676. 


DBG>CANCEL MODULE MEANSUB$MAIN 


dbg>show MODULE 


module name 

symbols 

language 

size 

BAS$MSGDEF 

no 

BLISS 

68 

BAS$ST0P 

no 

BLISS 

284 

MEANSUB$MAIN 

no 

BASIC 

172 

0TS$LINKAGE 

yes 

MACRO 

100 


total modules: 4. 


remaining size: 60856. 


dbg>set MODULE/ALL 


dbg>show MODULE 


module name 

symbols 

language i 

Bize 

BAS$MGSDEF 

yes 

BLISS 

36 

BASSSTOP 

yes 

BLISS 

172 

MEANSUBSMAIN 

yes 

BASIC 

172 

OTS$LINKAGE 

yes 

MACRO 

100 

total modules: 

4. 

remaining si: 

dbg> show module foo,MAIN,SUB* 


module name 

symbols 

language 

size 

FOO 

yes 

MACRO 

432 

MAIN 

no 

FORTRAN 

280 

SUB1 

no 

FORTRAN 

164 

SUB2 

no 

FORTRAN 

204 

total modules: 

4. 

remaining 

size: < 


60452. 


60720. 


This scope search list is based on your current PC and changes dynamically 
as your program executes. The default scope means that, when you do not 
specify a path name, a symbol lookup such as "EXAMINE X" first looks for 
X in the routine that is currently executing (scope 0); if no X is visible there, 
the debugger looks in the caller of that routine (scope 1), and so on down the 
call stack; if X is not found in scope N, the debugger searches the rest of the 
run-time symbol table (RST), then searches the global symbol table (GST), if 
necessary. 

You can set up a symbol scope search list by specifying more than one 
parameter in the SET SCOPE command. The debugger uses the first 
parameter specified as a path-name prefix to interpret a symbol without a 
path-name prefix. If this interpretation fails, the debugger uses the next 
parameter listed in the SET SCOPE command in a similar fashion and 
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continues until it successfully interprets the symbol or until it exhausts the 
parameters specified in the SET SCOPE command. 

The acceptable parameters to the SET SCOPE command are described below. 

MODULE\ROUTINE\BLOCK This is a legal path name. Path names may be 

complete or incomplete. Note that there may be 
one or more routines and/or blocks. 

0, 1, 2, 3, . . . These numbers are numeric path names. The 

numeric path name 0 specifies that symbols 
without path-name prefixes are to be interpreted 
as if they appeared in the currently active routine; 
numeric path name 1, in the program unit that 
contains the call to the currently active routine; 
numeric path name 2, in the program unit that 
contains the call to the program unit that contains 
the call to the currently active routine; and so on. 

Backslash (\) The backslash (\) specifies that a symbol without 

a path-name prefix is to be interpreted as a global 
symbol. 

The following is an example of the SET SCOPE command: 

DBG>SET SCOPE 1, MODB, \ 

This command establishes a symbol scope search list. As a result of this 
command, the debugger attempts to interpret a symbol without a path-name 
prefix as if (1) it appeared in the program unit that contains the call to 
the currently active routine, (2) it appeared in MODB, (3) it were a global 
symbol. 

If you want to examine the current parameters in effect, issue the SHOW 
SCOPE command. 

If you want to change the existing scope search list, issue a SET SCOPE 
command specifying the desired parameters. 

If you want to cancel the existing scope search list, issue the CANCEL SCOPE 
command. 

The CANCEL SCOPE command has the same effect as the SET SCOPE 0 
command. 


4.5.4 The SHOW SYMBOL Command 

You can use the SHOW SYMBOL command to ask the debugger for 
information that it has in its symbol table. You can request information 
about a single symbol or about all symbols (by using wildcards). 

The following example shows how an attempt to examine X fails because 
there are two X's in the program. SHOW SYMBOL displays the two instances 
of X. 

DBG> EXAM X 

‘/.DEBUG-W-NOUNIQUE, X is not unique 

DBG> SHOW SYMBOL X 

data F00\X 

data FUM\X 

DBG> EXAMINE F00\X 

F00 
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To display type and address information about all the symbols in the RST, 
enter the following command string: 

DBG> SHOW SYMBOL/TYPE/ADDRESS * 

The asterisk (*) is the wildcard character. It matches all symbols. 

For more information about SHOW SYMBOL, see the Command Dictionary. 


4.6 Debugging Shareable Images 

A shareable image is an image that is not directly executable. Shareable 
images are included in the linking of executable images, and then the 
shareable image is loaded at run-time when the executable image is run. 

A shareable image contains "universal symbols" that are visible from the 
executable image. See the VAX/VMS Linker Reference Manual for more 
information on shareable images. 

You debug a shareable image in much the same way as any other image. 

You first compile and link the shareable image with the /DEBUG qualifier. 
You need not install the shareable image to debug it. Instead, you can debug 
your own private copy by pointing a logical name to it. You will be using the 
debugger's SET IMAGE and SHOW IMAGE commands. 

The following is a simple example to illustrate the above points. Suppose 
MAIN.FOR is the source file for your main image, and SFLARE.FOR is the 
source file for the shareable image that you want to debug. Assume that 
SHARE.FOR has a single universal symbol, SHARED-ROUTINE, which is a 
routine called from the main program MAIN.FOR. 

To debug SHARE.FOR, first compile and link the shareable image with the 
/DEBUG option: 

$ FORTRAN/DEBUG/NOOPT SHARE 
$ LINK/SHARE/DEBUG SHARE. SYS$INPU T/OPTION 
UNIVERSAL=SHARED_ROUTINE ICTRL/Zl 

You have now built the shareable image SHARE.EXE in your current 
directory. Since it is a shareable image, you cannot run SHARE.EXE directly. 
Instead, you have to link your main image against it, then point the logical 
SHARE to your copy of SHARE.EXE, and then run the main image: 

$ FORTRAN/DEBUG/NOOPT MAIN 
$ LINK/DEBUG MAI N,SYS$IN PUT/OPTION 
SHARE.EXE/SHARE |CTRL/Z| 

$ DEFINE SHARE SYS$DISK:[]SHARE.EXE 
$ RUN MAIN 

VAX DEBUG Version 4.4 

‘ADEBUG-1 - INITIAL, ... 

DBG> 

Now, suppose you want to set a breakpoint on SHARED—ROUTINE, the 
routine in your shareable image. To do that, you "set" the shareable image 
SHARE to bring in its symbol table. The symbol SHARED—ROUTINE is then 
available to the debugger, and you can set a breakpoint on it: 

DBG> SET BREAK SHARED.ROUTINE 

•/.DEBUG-W-NOSYMBOL, symbol ’ SHARED_ROUTINE’ not found 
DBG> SHOW IMAGE 


set base address end address 


image name 

♦MAIN 

SHARE 


yes 

no 


00000200 
0000i000 


000009FF 

00001FFF 
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total images: 2 
DBG> SET IMAGE SHARE 
DBG> SHOW IMAGE 

image name 

MAIN 
♦SHARE 

total images: 2 
DBG> SET MODULE/ALL 
DBG> SET BREAK SHARED.ROUTINE 
DBG> GO 

break at routine SHARED.ROUTINE 

10: subroutine shared_routine(a,b) 

DBG> 

Now that you have set image SHARE and all its modules and have reached 
the breakpoint at SHARED_ROUTINE, you can debug it in the normal 
fashion (for example, step through the routine, examine variables, and so on). 


remaining size: 32856 

set base address end address 

yes 00000200 000009FF 

yes 00001000 00001FFF 

remaining size: 32856 
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Referencing Program Locations 


In debugging, you make references to program locations in order to stop 
program execution, to examine and deposit values, and to set breakpoints, 
watchpoints, and tracepoints. 

All references to program locations are called address expressions. An address 
expression may be a simple address or an expression consisting of one or 
more simple addresses, operators, and delimiters. 

Generally, when the debugger interprets an address expression, the results 
are a program location and a type that is associated with the contents of that 
location. 

The first part of this chapter contains a discussion of type; the second part, a 
description of various simple addresses; and the third part, a discussion of the 
use of operators and delimiters to form expressions. 


5.1 Type 


When a symbol is declared in the source language, the language compiler 
associates a type with the entity that the symbol represents. Thereafter, the 
entity is interpreted in that language-dependent (or compiler-generated) type. 
In general, the debugger understands language-dependent types that are 
associated with entities by declaration in the source language. 

However, because all references are not symbolic, an entity may not have 
a compiler-generated type. In this case, the entity is interpreted using a 
debugger default type. The default type is used only when the entity has no 
type associated with it already. 

The following are the debugger types: 


ASCILn 

ASCIC 

ASCID 

ASCIW 

ASCIZ 

BYTE 

DATE_TIME 

D-FLOAT 


FLOAT 


G-FLOAT 


Designates the ASCII character string type (length n bytes) 
Designates the counted ASCII character string type 
Designates a string descriptor pointing to an ASCII string 
Designates a varying ASCII character string 
Designates a zero-terminated ASCII character string 
Designates the byte integer type (length 1 byte) 

Designates the 64-bit VMS representation of date and time. 

Designates the D_floating type (length 8 bytes), whose value 
range is the same as the F_floating type but with approximately 
16 decimal digits precision 

Designates the F_floating type (length 4 bytes), whose values 
may range from .29*10 38 to 1.7*10 38 with approximately 7 

decimal digits precision 

Designates the G_floating type (length 8 bytes), whose values 
may range from .56* 10 --308 to .9*10 308 with approximately 
15 decimal digits precision 
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H_FLOAT 


INSTRUCTION 

LONGWORD 

OCTAWORD 

PACKED:n 

QUADWORD 

WORD 


Designates the H_floating type (length 16 bytes), whose 
values may range from .84*10— 4932 to .59* 10 4932 with 
approximately 33 decimal digits precision 

Designates the VAX instruction type (variable length) 
Designates the longword integer type (length 4 bytes) 

Designates the octaword integer type (length 16 bytes), whose 
values are signed integers in the range -2 127 to 2 127 -1 

Designates a packed decimal type (length n digits). 

Designates the quadword integer type (length 8 bytes), whose 
values are signed integers in the range -2 63 to 2 63 -1 

Designates the word integer type (length 2 bytes) 


To change the default type, specify the desired type as a parameter in the 
SET TYPE command. 

For example, the following command changes the default type to 6-byte 
ASCII string: 

DBG>SET TYPE ASCII:6 

As a result of this command, the debugger interprets any entity without a 
compiler-generated type as a 6-byte ASCII string. 

To see what the current default type is, issue the SHOW TYPE command. 

If you want all entities, even those with compiler-generated types, to be 
interpreted in one of the above types, you establish an override type by 
specifying the desired type as a parameter in the SET TYPE/OVERRIDE 
command. 

For example, the following command directs the debugger to interpret all 
entities, even those with compiler-generated types, as VAX instructions: 

DBG>SET TYPE/OVERRIDE INSTRUCTION 

To see what override type is in effect, issue the SHOW TYPE/OVERRIDE 
command. 

To cancel an override type, issue the CANCEL TYPE/OVERRIDE command. 

If you want the debugger to interpret an entity in one of the above types, but 
only for the duration of the command that mentions the entity, specify the 
desired type as a command qualifier. A type specified as a command qualifier 
is a command override type. For example, the following command directs the 
debugger to interpret the entity RADIUS as a byte integer: 

DBG>EXAMINE/BYTE RADIUS 

As a result of this command, any associated compiler-generated type or 
current override type established by the SET TYPE/OVERRIDE command is 
overridden for the duration of the command. 

To sum up, you can control the type used by the debugger to interpret an 
entity in three ways. In increasing order of power, these are 

• Setting the default type by the SET TYPE command 

• Setting an override type by the SET TYPE/OVERRIDE command 

• Specifying a command override type by using a type command qualifier 
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Thus, a command override type overrides any compiler-generated type, 
default type, or override type; an override type overrides any compiler¬ 
generated type or default type; a compiler-generated type overrides the 
default type; and the default type, being the weakest type, overrides no other 
type. 

See Chapter 6 for examples of how these types are used in debugging. 


5.1.1 The Type Associated with Address Expressions 

The type associated with an address expression depends on the current 
default type, any override types currently in effect, and on the address 
expression itself. 

The debugger associates a type with an address expression in the following 
way: 

1 If an address expression is found in a command that contains a type 
command qualifier, then the type specified by the qualifier is associated 
with the address expression. 

2 If an address expression is found in a command that does not contain a 
type command qualifier, then any override type established by the SET 
TYPE/OVERRIDE command is associated with the address expression. 

3 If a type is not associated with the address expression in one of the above 
ways, then the type associated with the address expression depends on 
the address expression itself. 

• An address expression that consists of a single, symbolic reference 
has the type associated with that reference by the source language 
(the compiler-generated type). 

• The debugger symbols for current entity, logical predecessor, and 
logical successor have the type associated with the address expression 
for which they are an abbreviation. 

4 If a type is not associated with the address expression in one of the above 
ways, then the address expression is given the default type. 


5.2 Simple Addresses 

You can make references to program locations using symbolic notation 
present in your program, as well as other notation generated by the language 
compiler and notation peculiar to the debugger itself. Taken as a whole, these 
forms of notation are called simple addresses. 

This section presents each form of simple address and explains how the 
debugger interprets it. 
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5.2.1 Symbolic References 

Symbolic references are program location references that use program 
symbols, with or without path-name prefixes. 

A symbolic reference may be a source-language symbol or a symbol created 
with the debugger DEFINE command. 

In the following examples, the symbolic references DAT1 and 
ROUTINE\BLOCK\DATl are simple addresses in the debugger EXAMINE 
command: 

DBG>EXAMINE DAT1 
DBG>EXAMINE R0UTINE\BL0CK\DAT1 

Both commands direct the debugger to display the value of DAT1 in its 
compiler-generated type. 


5.2.2 Line Numbers 


Some language compilers generate line numbers so that references to program 
locations can be found more easily. 

In a debugging session, you can use these line numbers to refer to lines of 
code in your program. When the debugger encounters the %LINE symbol, it 
interprets the number that follows as a compiler-generated line number and 
uses it as a simple address to reference that location. 

The following example shows how the %LINE symbol, together with a line 
number, is used as a simple address: 

DBG>SET BREAK ‘/.LINE 232 

If you want to use line numbers as simple addresses, you might find that 
having a compiler listing is helpful because it lists, among other things, each 
line of code with its corresponding line number. For more information on 
obtaining a compiler listing, refer to the user's guide for the language you are 
using. 

You may also use line numbers with path-name qualification as simple 
addresses. The path name precedes the entire line number notation, as 
follows: 

MODULE\%LINE 30 

The %LINE symbol can be used to identify anonymous blocks. See 
Section 4.5.1 for an example of the %LINE symbol used in this way and 
for more information about the %LINE symbol. 
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5.2.3 Statement Numbers 

In those languages that allow more than one statement on a line, statement 
numbers are used to differentiate among statements on the same line. 

A statement number consists of a line number, followed by a period and a 
number indicating the statement. The format follows: 

•/.LINE xxx.yy 

In this format, xxx is the line number and yy is a number specifying the 
statement. The number one (1) represents the first statement that begins on 
the line; the number two (2), the second; and so on. 

For example, in VAX BASIC, the second statement on line 500 is expressed as 
follows: 

‘/.LINE 500.2 

You may also use statement numbers with path-name qualification as simple 
addresses. The path name precedes the entire statement number, as follows: 

M0DULEX7.LINE 30.3 


5.2.4 Numeric Labels 


In some languages, numeric labels are used to label lines of source code in a 
program. You can use these labels to reference lines of code in a debugging 
session by prefixing them with the %LABEL symbol. 

The format of a reference to a numeric label in the debugger syntax is 

•/.LABEL xxx 

Here, xxx is a user-defined numeric label. 

For example, in VAX FORTRAN, a numeric label is a number you place in a 
designated column of your program at an important program location so that 
you can reference that location. In debugging your program, you must prefix 
a reference to a numeric label with the % LABEL symbol. 

Example 5-11 shows part of a compiler listing of a VAX FORTRAN program. 
The numbers in the leftmost column are line numbers; you refer to them in a 
debugging session using the %LINE prefix. The numbers in the next column 
to the right are numeric labels; you refer to them in a debugging session using 
the %LABEL prefix. 

The following debugger command halts program execution at numeric label 
20 in the VAX FORTRAN program shown in Example 5-11: 

dbg>set BREAK '/.LABEL 20 

Note that program execution is stopped at the same program location if the 
following command is issued: 

DBG>SET BREAK '/.LINE 12 

You can use a numeric label with path-name qualification as a simple address. 
The path name precedes the entire line numeric label, as follows: 

CIRCLEV/.LABEL 10 
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Example 5-11 Line Numbers and Numeric Labels 


C PROGRAM TO FIND THE AREA 

C OF A CIRCLE 


0002 1 

0003 5 

0004 

0005 10 


0001 


PROGRAM CIRCLE 
TYPE 5 

FORMAT (’ ENTER RADIUS VALUE ’) 
ACCEPT 10,RADIUS 


0006 

0007 

0008 

0009 


FORMAT (F6.2) 

IF (RADIUS .LE.0) GO TO 20 


PI = 3.1415927 
AREA = PI*RADIUS**2 
TYPE 15,AREA 


0010 15 

0011 

0012 20 

0013 25 

0014 

0015 30 

0016 


FORMAT (’ AREA OF CIRCLE EQUALS \F10.3) 

GO TO 30 
TYPE 25 

FORMAT (’ PLEASE TYPE A POSITIVE NUMBER’) 

GO TO 1 

STOP 


END 


5.2.5 Numeric Literals 


A numeric literal is any character string in the source language that is a 
constant but not a symbol. The debugger can interpret numeric literals in a 
variety of ways. 

If you use a numeric literal in a simple address, the debugger interprets it as a 
virtual memory address. On the other hand, a literal in an address expression 
is treated as an offset from a program location. Positive and negative numbers 
indicate offset direction. 

In the following example, the debugger interprets the numeric literal 5032 as 
a virtual memory address: 

DBG>EXAMINE 5032 

In the example below, the literal 4 is treated as a 4-byte offset from the 
memory address represented by OPT. This debugger command deposits the 
value of X, which is interpreted as a byte integer, in the program location 
specified by the address expression OPT+4. 

dbg>deposit/byte OPT+4 = X 

In the evaluation of an address expression containing a literal of a type other 
than integer (such as floating point, bit string, or complex), the debugger 
attempts to convert that literal into integer form in the semantics of the source 
language. If the source language supports such conversion, the debugger uses 
the resulting integer value. However, if the conversion is not supported, the 
debugger issues an error message. 

In addition, you can use radix operators with any legal, source-language 
numeric literal. They cause the debugger to interpret your input in the radix 
you have specified. Legal radix operators are listed below. 

%BIN Causes the debugger to interpret the number in binary radix 

%DEC Causes the debugger to interpret the number in decimal radix 

%HEX Causes the debugger to interpret the number in hexadecimal radix 

%OCT Causes the debugger to interpret the number in octal radix 
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5.2.6 Current Entity Symbol 

The two current entity symbols are the period and the debugger permanent 
symbol %CURLOC. You may use them to make a reference to the program 
location last referenced by an EXAMINE or DEPOSIT command. 

In other words, whenever either of the commands below is executed, the 
value of the current entity is set equal to the value of the address-expression 
in that command. 

• EXAMINE address-expression 

• DEPOSIT address-expression = value 

Further, the debugger interprets the value of the current entity in the 
type associated with the address-expression in the EXAMINE or DEPOSIT 
command that set the current entity. 

In Example 5-12, EXAMINE RADIUS sets the current entity. The command 
"EXAMINE results in a display of the name of the current entity 
(CIRCLE\RADIUS) and the value of the current entity in the floating point 
type. 


Example 5-12 Examining the Current Entity 


DBG> EXAMINE RADIUS 

ISets current entity 

CIRCLEXRADIUS: 0.0000000E+00 

!symbol. 

DBG> EXAMINE . 

!Current entity is 

CIRCLEXRADIUS: 0.0000000E+00 

!RADIUS. Display type 
fused is the type 
!of RADIUS. 

DBG> DEPOSIT PI = 3.141593 

ISets current entity. 

!symbol. 

DBG> EXAMINE ‘/.CURLOC 

CIRCLEXPI: 3.141593 

!Current entity is PI. 


5.2.7 Logical Predecessor Symbols 

The two logical predecessor symbols are the circumflex (*) and the debugger 
permanent symbol %PREVLOC. When the current entity symbol refers to 
an entity in an aggregate such as an array, you may use either of the logical 
predecessor symbols to refer to that entity in the aggregate that is logically 
prior to the current entity. 

The logical predecessor of an entity may not be its physical predecessor; that 
is, the logical predecessor may not occupy the region of physical storage 
directly preceding that of the current entity. Such is the case, for example, 
when the current entity refers to the cell of a disconnected array A(2) whose 
logical predecessor A(l) is not stored physically adjacent to A(2) in memory. 
On the other hand, the logical predecessor of an entity may also be its 
physical predecessor. For instance, in a connected array, A(l) is both the 
logical and physical predecessor of A(2). 

In some cases the current entity may not have a logical predecessor. For 
instance, the first cell of an array A(l) has no logical predecessor, and hence 
its physical predecessor is logically unrelated to it. 


5-7 













Referencing Program Locations 


As with the current entity, the debugger uses type and symbolic information 
associated with the logical predecessor. 

Example 5-13 demonstrates how to use the logical predecessor symbol to 
examine the cells of an array. 


Example 5-13 Using the Logical Predecessor Symbol 


DBODEPOSIT CHAR(l) = ’1234567890’ 

ISets current entity 
!symbol. 

DBODEPOSIT CHAR(2) = ’ABCDEFGHIJ’ 

ISets current entity 
!symbol. 

DBODEPOSIT CHAR(3) = ’abcdefghij’ 

ISets current entity 

I symbol. 

DBOEXAMINE . 

M0D\CHAR(3): abcdefghij 

I Examines current entity 

I which is CHAR(3). 

DBOEXAMINE ~ 

M0D\CHAR(2): ABCDEFGHIJ 

{Logical predecessor is 

I previous array member 

ICHARC2). 

DBOEXAMINE ‘/.PREVLOC 

M0D\CHAR(1): 1234567890 

I Logical predecessor is 

I previous array member 

I CHAR(1). 


5.2.8 Logical Successor Symbols 

The logical successor symbols are the RETURN key and the debugger 
permanent symbol %NEXTLOC. You may use them to make a reference 
to the program location that logically follows the current entity. To examine 
the logical successor of the current entity with the RETURN key, for instance, 
you enter the EXAMINE command without an operand and then press 
RETURN. 

The logical successor of an entity may not be its physical successor; that is, 
the logical successor may not occupy the region of physical storage directly 
following that of the current entity. Such is the case, for example, when the 
current entity refers to the cell of a disconnected array A(2) whose logical 
successor A(3) is not stored physically adjacent to A(2) in memory. On 
the other hand, the logical successor of an entity may also be its physical 
successor. For instance, in a connected array, A(3) is both the logical and 
physical successor of A(2). 

In some cases the current entity may not have a logical successor. For 
instance, the last cell of an array has no logical successor, and hence its 
physical successor is logically unrelated to it. 

As with both the current entity and logical predecessor, the debugger uses 
type and symbolic information associated with the logical successor. 

Example 5-14 demonstrates how the logical successor symbol may be used to 
examine succeeding cells in an array. 
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Example 5-14 Using the Logical Successor Symbol 


DBG>DEPOSIT CHAR(l) = ’1234567890’ 


DBG> DEPOSIT CHAR(2) = ’ABCDEFGHIJ’ 
DBG>DEPOSIT CHAR(3) = ’abcdefghij’ 


DBG> EXAMINE CHAR(l) 
M0D\CHAR(1): 1234567890 


'Sets current entity 
!symbol. 


DBG>EXAMINE 1 RET 1 
M0D\CHAR(2): ABCDEFGHIJ 


{Logical successor is 
!CHAR(2). 


DBG>EXAMINE 7.NEXTL0C 
M0D\CHAR(3): abcdefghij 


SNext logical successor 
Sis CHAR(3). 


5.3 Address Expressions 


An address expression specifies a (possibly) typed program location. It may 
consist of a single operand (a simple address) or of many operands together 
with operators and delimiters. 

The debugger evaluates an address expression according to its own rules, 
which are similar to those used to evaluate an expression in a programming 
language. Both an expression and an address expression may include 
operators and delimiters, and both are evaluated according to rules of 
precedence. The result of the evaluation of an address expression is a 32-bit 
longword integer that represents a program location. 

In an address expression, an operand may be one of the following: 

• A simple address 

• A unary operator with an operand 

• A binary operator with two operands 

• An address expression surrounded by parentheses 


5.3.1 Operands 


Operands in address expressions may be simple addresses, as defined in 
Section 5.2, or subexpressions, where a subexpression is an expression within 
an expression. The operands in a subexpression may be simple addresses or 
other subexpressions. 

In the following example, the simple address %LINE 40 is used as an operand 
in an address expression that also contains the literal 2 as an operand, a 
multiplication operator, and delimiters. 

DBG> EXAMINE (‘/.LINE 40) *2 

This command displays the value at the program location whose address is 
twice that of %LINE 40. 

In the next example, the address expression (X+4)*2 consists of two operands: 
the subexpression (X+4) and the literal 2. 

DBG> EVALUATE/ADDRESS (X+4)*2 

This command calculates the virtual memory address denoted by the address 
expression (X+4)*2. 
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In the next example, the address expression ((X-8)*2)+4 contains two 
subexpressions. The larger subexpression ((X-8)*2) is delimited so as to be 
one operand for the addition operator, the other operand being the literal 4. 
The smaller subexpression (X-8) is contained within the larger subexpression 
and is one of the operands for the multiplication operator, the other operand 
being the literal 2. 

DBODEPOSIT ((X-8)*2)+4 = Q 

This command deposits the value Q in the location represented by the address 
expression ((X-8)*2)+4. 


5.3.2 Operators 


An operator with one operand is called a unary operator; an operator with 
two operands is called a binary operator. 

Legal operators are listed below. 


Plus sign ( + ) 


Minus sign (-) 


Multiplication sign (*) 

Division sign (/) 

At sign (@) 

Period (.) 


Can be either a unary or binary operator. As a unary 
operator, the plus sign indicates the unchanged 
value of its operand. As a binary operator, the plus 
sign adds the preceding operand and succeeding 
operand together. 

Can be either a unary or binary operator. As a unary 
operator, the minus sign indicates the negation of 
the value of its operand. As a binary operator, the 
minus sign subtracts the succeeding operand from 
the preceding operand. 

Is a binary operator. It multiplies the preceding 
operand by the succeeding operand. 

Is a binary operator. It divides the preceding 
operand by the succeeding operand. 

Are both unary operators. The at sign (@) and the 
period function as "contents" (of) operators. The 
"contents of" operator causes its operand to be 
interpreted as a virtual address and thus requests 
the "contents of" (or value residing at) that address. 


For example, assume that the value of pointer 
variable PTR is 7FF00000 hexadecimal, the virtual 
address of an entity that you want to examine. 
Assume further that the value of this entity is 
3FF00000 hexadecimal. The following command 
demonstrates how the "contents of" operator is 
used to examine the entity: 

DBG> EXAMINE/LONG .PTR 
7FF00000: 3FF00000 
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Bit field <p,s,e> Is a unary operator. You can apply bit field selection 

to an address-expression. To select a bit field, 
you must supply a bit offset (P), a bit length (S), 
and a sign extension bit (E), which is optional. For 
example, to examine the address-expression X_ 
NAME starting at bit 3 with a length of 4 bits and 
no sign extension, you would issue the command as 
follows: 

DBG> EXAMINE X.NAME <3,4,0> 


5.3.3 Precedence 


Rules of precedence determine the sequence in which the operations of an 
expression are carried out. Although the debugger evaluates expressions 
according to its own rules of precedence, which are language independent, its 
rules are identical to those of most programming languages. 

The order in which the operations within an address expression are carried 
out is determined by the following three factors, listed in decreasing order of 
precedence (first listed have higher precedence): 

1 The use of delimiters (usually parentheses or brackets) to group operands 
with particular operators 

2 The assignment of relative priority to each operator 

3 Left-to-right priority of operators 

The following are the legal debugger operators, listed in decreasing order of 
precedence. 

1 Unary operators ((.), (@), (+), (-)) 

2 Multiplication and division operators ((*), (/)) 

3 Addition and subtraction operators ((+), (-)) 

For example, in the evaluation of the following address expression, the 
debugger first adds the operands within parentheses, then divides the result 
by 4, then subtracts the result from 5. 

5-(T+5)/4 


5.3.4 The EVALUATE/ADDRESS Command 

The debugger interprets the operand of an EVALUATE/ADDRESS command 
as a language-independent address expression, evaluates the address 
expression using its own rules for expression evaluation (which are similar to 
those of most languages), and displays the value of the address expression as 
a virtual address. 

The format of the EVALUATE/ADDRESS command is 

EVALUATE/ADDRESS address-expression [.address-expression...] 

If you specify a radix mode command qualifier, the debugger displays the 
value of the address expression as a virtual address in that radix. 
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You can evaluate more than one address expression in a single EVALUATE 
/ADDRESS command by separating address expressions with a comma. 

Any address expression, as discussed in this section, may be used with the 
EVALUATE/ADDRESS command. 

The EVALUATE/ADDRESS command is useful in determining the virtual 
addresses of symbols and of expressions that either contain or do not contain 
symbols. Example 5-15 shows how this command is used. 


Example 5-15 Using the EVALUATE/ADDRESS Command 


DBG>EVALUATE/ADDRESS RADIUS !For determining the 

1024 laddress of a symbol. 


DBG>EVALUATE/ ADDRESS 1024 + 40 !For performing address 
1064 !arithmetic. 


DBG>EVALUATE/ ADDRESS (RADIUS + 4)/2 
514 
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Examining and Depositing Data 


This chapter explains how to use the EXAMINE, DEPOSIT, and EVALUATE 
commands, and how to control the modes and types used by the debugger. 
The first part of this chapter discusses the modes you can use to control 
the interpretation of address expressions and language expressions. For 
information on types, see Section 5.1. 



6.1 


Modes 





The SET MODE command and SET RADIX command let you control how 
the debugger interprets information you enter in debugger commands, as well 
as how it displays the results of command execution. A command summary 
follows. Note that the SET MODE command is also used to control functions 
that are not related to the interpretation of data or addresses. 


D_floating 
G—floating 


Radix 


The SET MODE [NO]G_FLOATING command specifies 
that all double-precision constants you enter in 
expressions should be interpreted as G_floating constants 
or D_floating constants. 

Radix influences the interpretation of numeric literals and, 
under certain circumstances, the display of data. Radix 
may be established by three methods: 

• A command qualifier specifying the radix 

• The SET RADIX/OVERRIDE command 

• The SET RADIX command 


A SET RADIX/OVERRIDE command overrides the effect 
of a SET RADIX command, and both commands can 
be overridden by a radix qualifier on the EXAMINE and 
EVALUATE commands. 

Keywords are BINARY, DECIMAL, HEXADECIMAL, and 
OCTAL. They can be used either as parameters to the 
SET RADIX/OVERRIDE and SET RADIX commands or as 
command qualifiers on certain commands. 

Symbolic The SET MODE [NO]SYMBOL command influences the 

Nonsymbolic amount of symbolization the debugger performs. 


To display the current modes, issue the SHOW MODE command. 

The following sections discuss radix mode and symbolic mode in more detail. 
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6.1.1 Radix Modes 


You can direct the debugger to interpret and display numbers in any one of 
four radixes: BINARY, DECIMAL, HEXADECIMAL, and OCTAL. DECIMAL 
is the default radix for most languages. For BLISS and MACRO, however, the 
default radix is HEXADECIMAL. 

You can set radix in one of the following three ways: 

A Command Qualifier 

For certain commands, you can override the current radix mode for the 
duration of a command by using a radix mode command qualifier. The radix 
mode that you specify overrides all other radix modes. The qualifiers are 
/BINARY, /DECIMAL, /HEXADECIMAL, and /OCTAL. For example, if the 
radix mode is set to decimal (the default) but you want to have the value of 
a program location STATSBLK displayed in binary, you specify the command 
qualifier as follows: 

DBG>EXAMINE/BIN STATSBLK 

This command causes the debugger to display STATSBLK as a binary integer 
regardless of any other radix information the debugger currently has. 

A radix mode command qualifier controls output radix only; it does not 
control the input radix. You can, however, set the input radix for an 
expression with four radix operators: 

%BIN Indicates that the debugger should treat the input radix as binary 

%DEC Indicates that the debugger should treat the input radix as decimal 

%HEX Indicates that the debugger should treat the input radix as hexadecimal 

%OCT Indicates that the debugger should treat the input radix as octal 

The SET RADIX/OVERRIDE Command 

The next most powerful way to establish radix mode is with the SET RADIX 
/OVERRIDE command. Keywords are BINARY, DECIMAL, HEXADECIMAL, 
and OCTAL. For example, the command sequence 

DBG>SET RADIX/OVERRIDE OCT 
DBG>EXAMINE STATSBLK 

displays STATSBLK as an octal integer, overriding any type information the 
debugger currently has about STATSBLK. To cancel the radix override, issue 
the CANCEL RADIX/OVERRIDE command. 

The SET RADIX Command 

The weakest way to establish radix mode is with the SET RADIX command. 

It causes the debugger to display any integer values (including addresses) 
using the radix you specified on the SET RADIX command. However, other 
values (such as floating or enumeration type values) are to be displayed as 
they normally would. For example, the command sequence 

DBG>SET RADIX HEX 
DBG>EXAMINE 1000 
DBG>EXAMINE STATSBLK 

displays the integer value 1000 as a hexadecimal integer. However, the 
variable STATSBLK is displayed according to its type. 
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When the debugger evaluates a source-language expression or an address 
expression, it interprets numeric literals within that expression in the current 
input radix mode. 

When the debugger evaluates an address expression or a source-language 
expression, it displays the result in the current output radix mode unless a 
radix mode command qualifier is specified. In that case, the debugger displays 
the result in the mode specified by the command qualifier. 

Note that when you enter a hexadecimal value that begins with a letter, 
you must prefix that value with a zero; otherwise the debugger attempts to 
interpret the entry as a symbol. 

The radix mode specified by a command qualifier overrides both the other 
ways to establish radix mode. Likewise, the radix mode specified with the 
SET RADIX/OVERRIDE command overrides any radix mode specified with 
the SET RADIX command. 

Although the SET RADIX command has the same effect as a SET MODE 
command, the SET RADIX command is the preferred way to specify radix 
information. 

To cancel modes established by the SET MODE command, issue the CANCEL 
MODE command. 

After the debugger executes the CANCEL MODE command, default modes 
are in effect. 

Example 6-16 shows how radix modes are used in EXAMINE, EVALUATE, 
and EVALUATE/ADDRESS commands. 


6.1.1.1 Radix Operators 

By using a radix operator, you can direct the debugger to interpret a numeric 
literal in binary (%BIN), decimal (%DEC), octal (%OCT), or hexadecimal 
(%HEX) radix, provided that the numeric literal is legal for that radix. 

Radix operators are useful when you want to enter several numeric literals 
of different radixes in a single debugger command. By using radix operators, 
you can specify the radix for each individual numeric literal. 

Radix operators are also useful when you want to convert a number in one 
radix to another radix. For example, if you want to see what a decimal 1000 
is in hexadecimal, you can use the command 

dbg>ev/hex '/.dec 1000 
000003E8 

A radix operator has higher precedence than any other operator. For instance, 
the expression %HEX 20 + 33 treats 20 as a hexadecimal integer and 33 as a 
decimal integer (assuming that decimal is the default radix). However, the 
expression %HEX(20 + 33) treats both 20 and 33 as hexadecimal integers. 

You can also nest radix operators. For instance, %HEX(20 + %OCT 10 + 33) 
interprets 20 and 33 hexadecimal radix and 10 in octal radix. 

For example, assume you want to deposit a VAX instruction into a memory 
location denoted by an address expression that is a hexadecimal literal. 
Further, assume that one operand of the instruction is a decimal literal. 

You want the debugger to interpret these two numeric literals in their 
corresponding radixes. In this situation, you cannot use radix command 
qualifiers since they are not legal qualifiers for the DEPOSIT command. 

One way to do this operation is to use the %HEX radix operator (to affect 
the address expression) and a decimal (%DEC) radix operator (to affect the 
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instruction operand). The following example demonstrates such a situation in 
VAX MACRO: 

DBODEPO SIT/INSTRUCT I ON '/.HEX 5432 = ’MOVL ~0'/.DEC 222, R1 ’ 

In this command, the debugger interprets the literal 5432 in hexadecimal 
radix and the literal 222 in decimal radix. 

Example 6-16 Using Radix Mode 


DBOSHOW RADIX 

input radix: decimal 
output radix: decimal 
DBG> EVALUATE 10 
10 

! "10" is in decimal 
! for both input and 
! output 

DBG>EVALUATE/HEX 10 

0A 

! /HEX affects output only 

DBG>SET RADIX/OUTPUT HEX 
DBOSHOW RADIX 
input radix: decimal 
output radix: hex 
DBOEVALUATE 10 
0A 

! Input radix is decimal, 

! output radix is hex 

DBOSHOW MODE !Display default modes, 

modes: symbolic, noscreen, nokeypad 
input radix : decimal 
output radix: decimal 

DBOEXAMINE '/.LINE 14 

T0Y$MAIN\%LINE 14: CALLG W~128(R11), <BL~T0Y$MAIN+596 

•Default type of 7.LINE 
!is instruction. 

DBOE/HEX. !Hex representation of 

(instruction at 

1591: 00 000214FF 0080CBFA ! '/.LINE 14. Instruction 

(operands are in 
(hexadecimal radix. 


DBG>E PSL (Display PSL in 

T0Y$MAIN\%PSL: (decimal radix. 

CMP TP FPD IS CURM0D PRVM0D IPL DV FU IV T N Z V C 
0 0 0 0 USER USER 0 0 0 100000 


DBOE/HEX PSL 
TOY$MAIN\y,PSL: 


(Display PSL in 

03C000020 (hexadecimal radix. 


DBOSET RADIX HEX 


(Set default radix mode 
(to hexadecimal. 


DBOEXAMINE STATSBLK 

T0Y$MAIN\STATSBLK 

(1) : 00000004 

( 2 ) : 00000012 

(3) : 0000009A 

(4) : 00000173 

(5) : 00000C93 


(Examine the array 
(STATSBLK in hexadecimal 
(radix. 


(Continued on next page) 
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Example 6-16 (Cont.) Using Radix Mode 


DBG>SH0W RADIX !Display the current 

input radix : hexadecimal {default radixes. 

output radix: hexadecimal 


DBG>EXAMINE/BIN STATSBLK 


{Examine STATSBLK 


CONV_EX$MAIN\STATSBLK 

( 1 ): 00000000 00000000 

( 2 ): 00000000 00000000 

(3) : 00000000 00000000 

(4) : 00000000 00000000 

(5) : 00000000 00000000 


!in binary radix. 
00000000 00000100 
00000000 00010010 
00000000 10011010 
00000001 01110011 
00001100 10010011 


6.1.2 Symbolic and Nonsymbolic Modes 

In symbolic mode, which is the default, the debugger attempts to display all 
addresses symbolically. In nonsymbolic mode, the debugger does not attempt 
to symbolize addresses. This may increase the speed of command processing. 
An example follows: 

DBG>EVALUATE/ ADDRESS X 
512 

DBG>EXAMINE 512 
F00\X:0 

DBG>EXAMINE/NOSYMBOL 512 
512:0 


/NOSYMBOL also affects the display of instructions. An example follows: 


dbg>show mode 

modes: symbolic, noscreen, nokeypad 
input radix : decimal 
output radix: decimal 

dbg>examine/instruction OUT 

DRAW\0UT: CMPB B~DRAW\C0L,#0 


DBG>EXAMINE/INSTRUCTION/NOSYMBOL out 

DRAWXOUT: CMPB B~3599,#0 


{Display the new 
{default mode. 


Display OUT as an 
{instruction using 
!the default symbolic 
{mode. Note that the 
{instruction operand 
!DRAW\C0L is shown 
!symbolically. 

{Specify nonsymbolic 
{mode. Note that the 
{instruction operand 
!DRAW\C0L is now 
{expressed numeri- 
!cally. 


6.2 The EXAMINE Command 

You use the EXAMINE command in the following format to display the value 
of one or more program entities: 

EXAMINE [/qualifier...] [address-expression- 
[:address-expression] [,address-expression- 
[:address-expression]...]] 

If you specify a single address-expression parameter in the EXAMINE 
command, the debugger displays the value of the entity at the location 
denoted by the address expression in the type associated with that location. 
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You can examine more than one entity (a list) in a single EXAMINE command 
by entering more than one address expression and separating each with a 
comma. 

You can examine a range of entities in a single EXAMINE command by 
entering the address expression that denotes the first entity in the range, a 
colon, and the address expression that denotes the last entity in the range. A 
range is a contiguous sequence of program entities. 

You can also examine a list of ranges of entities in a single EXAMINE 
command by separating each range with a comma. 

When you examine the PSL, the debugger displays its contents in a formatted 
arrangement. 

Address expressions may take any of the forms discussed in Chapter 5. See 
Section 5.1.1 for a complete description of how the debugger associates types 
with address expressions. 

The following sections discuss the use of command qualifiers in the EXAMINE 
command, the examining of lists, the examining of ranges, and the examining 
of successive entities. 


6 . 2.1 


Command Qualifiers 


If you specify a type command qualifier in the EXAMINE command, the 
entity specified by the address expression is displayed in that type. The type 
command qualifiers follow: 


/ASCIC 

/ASCID 

/ASCILn 

/ASCIW 

/ASCIZ 

/BYTE 

/CONDITION—VALUE 


/D-FLOAT 

/DATE-TIME 

/FLOAT 

/G-FLOAT 

/H-FLOAT 

/INSTRUCTION 

/LONGWORD 


/QUADWORD 

/OCTAWORD 

/PACKED 

/PSL 

/PSW 

/SOURCE 

/WORD 


You may also specify the radix mode command qualifiers (/BINARY, 
/DECIMAL, /HEXADECIMAL, and /OCTAL) as well as the symbolic and 
nonsymbolic mode command qualifiers (/SYMBOL and /NOSYMBOL). See 
Section 6.1 for further information on the effects of specifying these mode 
command qualifiers. 

You can specify a type qualifier, a radix mode qualifier, and a symbolic 
/nonsymbolic mode qualifier in a single EXAMINE command. 

Example 6-17 demonstrates the use of these mode and type command 
qualifiers in the EXAMINE command. 
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Example 6-17 Using Mode and Type Qualifiers with the 
EXAMINE Command 


#1,B~44(R11) 


DBG> SET LANGUAGE FORTRAN 
DBG> SHOW MODE 

modes: nosymbolic, noscreen, nokeypad 
input radix : decimal 
output radix: decimal 

DBG>SHOW TYPE 
type: long integer 

DBG> EXAMINE ‘/.LINE 15 
T0YV/.LINE 15 : MOVL 

DBG> EXAMINE/BYTE . 

T0YY/.LINE 15 : -48 

DBG> EXAMINE/WORD . 

T0YY/.LINE 15 : 464 

DBG> EXAMINE/LONG . 

TOYY/.LINE 15 : 749404624 

DBG> E/QUAD . 

T0YV.LINE 15 

DBG> E/OCTAWORD 
T0Y'/,LINE 15 : 

DBG> E/FLOAT . 

T0Y7.LINE 15 : 

dbg>e/d_float . 

T0Y7.LINE 15 : 

DBG>E/G_FLOAT . 

TOY'/,LINE 15 : 

DBG>E/H_FLOAT . 

T0Y7.LINE 15 : 


+0130653502894178768 


!Set language to FORTRAN. 

!Display the current 
!default modes. 


!Display default type. 

!Display '/.LINE 15 in default 
!modes and type. 

!Type is byte integer. 

!Type is word integer. 

!Type is long integer. 

!Type is quadword integer. 


!Type is octaword integer, 
f5244643179280247008686078241046481 


1.9117807E-38 


1.9117807293306393E-38 


1.509506018605227E-300 


!Type is F_floating. 
!Type is D_floating. 
!Type is G_floating. 
!Type is H_floating. 


2.351187242166315296772081991217048E-4793 


DBG>EXAMINE/INSTRUCTION . 

T0YY/.LINE 15 : MOVL #1,B~44(R11) 

DBG> EXAMINE/ASCII . 

T0YV/.LINE 15 : " . . " 

DBG>EXAMINE/OCTAL . 

T0YY/.LINE 15 : 05452600720 

DBG>EXAMINE/DECIMAL . 

T0Y\'/.LINE 15 : 749404624 

DBG> EXAMINE/BYTE/HEX . 

T0YY/.LINE 15 : 0D0 

DBG>EXAMINE/BYTE/OCT . 

T0Y\'/.LINE 15 : 320 

DBG>EXAMINE/INSTRUCTION/BYTE . 
T0YV/.LINE 15 : -48 


!Type is VAX instruction. 

!Type is ASCII string. 

IRadix mode is octal. 

{Default type is longword. 

{Radix mode is decimal. 
{Default type is longword. 

{Type is byte. Radix mode is 
{hexadecimal. 

{Type is byte. Radix mode is 
{octal. 

{When two types are speci¬ 
fied, the last overrides the 
{first. 


6.2.2 Examining Instructions 

EXAMINE/INSTRUCTION will cause the debugger to display the examined 
location as an assembly language instruction. 

Note that "EXAMINE .PC" will display the instruction you are about to 
execute. The /INSTRUCTION qualifier is not needed in this case because the 
debugger knows that ".PC" is of type instruction. 
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Also note that subsequent EXAMINE commands will display succeeding 
instructions and subsequent EXAMINE ~ commands will display preceding 
instructions. The ability to examine backwards in the instruction stream is 
new with Version 4.0 of VAX/VMS. It is accomplished in a reliable way by 
backing up to a point we know about, such as the beginning of a line, and 
decoding forward from there. 

You may want to use these features in conjunction with the SET STEP 
INSTRUCTION command. 


6.2.3 Examining Lists 


You can examine any number of program locations using a single EXAMINE 
command by separating parameters in the command string with a comma. 
The format follows: 

EXAMINE address-expression, address-expression, ... 

The example below shows how you examine a list of three variables with a 
single EXAMINE command. 

DBOEXAMINE I,K,R 
T0Y\I: 0 
T0Y\K: 0 

T0Y\R: 0.0000000E+00 


6.2.4 Examining Ranges 

You can examine a range of successive program locations using a single 
EXAMINE command by specifying the first and last program locations in the 
range, in the following format: 

EXAMINE address-expressioni : address-expression2 

Address-expression 1 must have a smaller virtual memory address than 
address-expression2. Otherwise, the debugger issues an error message. 

As a result of this command, the debugger displays the entity specified 
by address-expressioni, the logical successor of address-expressioni, the 
next logical successor, and so on, until it displays the entity specified by 
address-expression2. 

The debugger associates a type with address-expressioni according to the 
rules described in Section 5.1.1. 

Note that you can use a single EXAMINE command to examine more than 
one range of program locations (in other words, a list of ranges) by separating 
ranges with a comma. The following is the format for specifying a list of 
ranges: 

EXAMINE address-expressioni : address-expression2, - 

addres8-expression3 : address-expression4, ... 

Note that the hyphen, which is the line continuation character, is used to 
continue the command string on a new line. 

Example 6-18 demonstrates the examination of ranges of program locations. 
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6.2.5 


Example 6-18 Examining Ranges of Program Locations 


DBOEXAMINE R: I !R has a 

'/.DEBUG-W-EXARANGE, invalid range of addresses !larger address 

!than I. 

DBOEXAMINE I:R 

T0Y\I: 555 

T0Y\J: 0 

T0Y\R: 0.0000000E+00 

!Modes are the defaults 
!symbolic and decimal. 

{Logical successor of I is 
!J. Logical successor of J 
!is R. I and J have the 
{type longword. R has the 
{floating type. 

DBOEXAMINE/BYTE I: R 

T0Y\I: 43 

T0Y\I+1: 2 

T0Y\I+2: 0 

T0Y\I+3: 0 

T0Y\J: 0 

TOYXJ+l: 0 

TOYXJ+2: 0 

TOYYJ+3: 0 

T0Y\R: 0 

{Byte is the override type. 

{The range of locations is 
{displayed as a series of 
{bytes. 

DBOEXAMINE/BYTE/NOSYMBOL I :R 

708: 43 

709: 2 

710: 0 

711: 0 

712: 0 

713: 0 

714: 0 

715: 0 

716: 0 

{Nonsymbolic mode causes 
!the location of each byte 
!to be displayed as a virtual 
{address, not as a 
!symbol. 

Example 6-19 Examining Successive Entities 

DBOEXAMINE I 

T0Y\I: 555 

{Default type is longword. 

DBOEXAMINE 1 RET | 

T0Y\J: 0 

{Display logical successor 
! of I. 

DBOEXAMINE '/.NEXTLOC 

T0Y\R: 0.0000000E+00 

{Display the next logical 
{successor of J. 

DBOEXAMINE I RET | 

T0Y\K: 0 

{Display the next logical 
!successor of R. 

DBOEXAMINE VECTOR(1) 

TOYXVECTOR(1): 0.0000000E+00 

{Display value of VECTOR(1). 

DBG>E 1 RET| 

TOYXVECTOR(2): 0.0000000E+00 

{Display logical successor. 


Examining Successive Entities 

You can examine the value of successive entities by using either the logical 
successor symbol RETURN or the debugger permanent symbol %NEXTLOC 
The debugger uses the type and mode associated with the current entity to 
interpret logical successors. 

Example 6-19 demonstrates how to examine successive entities using the 
logical successor symbols RETURN and %NEXTLOC: 
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6.2.6 Examining Values in Registers 

VAX provides 16 general purpose registers, some of which are used for 
temporary address and data storage. You can examine the contents of any 
register by specifying that register in an EXAMINE command, and you can 
deposit values into any register by specifying that register as the address- 
expression in a DEPOSIT command. For more information on depositing 
value in registers, see Section 6.3.5. 

The following symbols denote the 16 VAX registers. 

• The letter %R followed by a numeral from 0 through 11 represents the 
corresponding VAX general purpose registers, such as %R0, %R1, %R2, 
%R3, %R4, %R5, . . . %R11. In general, these symbols are debugger 
permanent symbols. 

• %PC represents the program counter and is a debugger permanent 
symbol. 

• %SP represents the stack pointer and is a debugger permanent symbol. 

• %AP represents the argument pointer and is a debugger permanent 
symbol. 

• %FP represents the frame pointer and is a debugger permanent symbol. 

You may abbreviate registers by leaving out the percent sign (for example, 

RO instead of %R0). However, if you do not use the percent character, the 
debugger may interpret these symbols as program variables you have defined, 
not as debugger permanent symbols. The debugger interprets these symbols 
as debugger permanent symbols only if your program does not contain 
variables of the same names. 

Example 6-20 demonstrates how to examine values in the VAX registers. 

Example 6-20 Examining Values in VAX Registers 


DBG>SH0W MODE !Display the current 

modes: nosymbolic, noscreen, nokeypad !default modes. 


input radix : decimal 
output radix: decimal 

DBG>SH0W TYPE 
type: long integer 

dbg>examine SP 
SP: 2147278720 

DBG>DEP0SIT .SP = 33 

dbg>examine . 
214727870: 33 

dbg>examine Rll 
Rll: 1024 


!Display current type. 

!Examine value of the stack 
!pointer. 

!Deposit 33 into .SP. 

!Check the value of .SP. 

!Examine contents of Rll. 


DBG>DEP0SIT Rll = 444 


{Deposit new value into Rll. 


DBG>EXAMINE Rll {Check the value of Rll. 

Rll: 444 
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6.2.6.1 The Processor Status Long word 

The PSL is a 32-bit VAX register whose value represents a number of 
processor state variables. The first 16 bits of the PSL (referred to separately 
as the processor status word, or PSW) contains unprivileged information 
about the current processor state; the values of these bits may be controlled 
by a user program. The latter 16 bits of the PSL, bits 16 through 31, contain 
privileged information and should not be altered by the user process. 

To examine the contents of the PSL, issue the command 

DBG>EXAMINE PSL 

The debugger displays the 32-bit PSL in the following format: 

PSL: CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV T N Z V C 
n n n n mode mode lv n n nnnnnn 

In this display, "n" may be 0 or 1; "mode" may be either KERN, EXEC, SUPR, 
or USER; and "lv," the interrupt priority level, may be a hexadecimal number 
from 0 through IF. 

You can also say EXAMINE/PSL to display any location in PSL format. This 
is useful for examining saved PSLs on the stack. 

For more information about the PSL, refer to Section 6.3.5.1. 

Example 6-21 demonstrates how to examine and modify the PSL. 

Example 6-21 Examining and Modifying the PSL 


DBOSHOW MODE !Display the current 

modes: nosymbolic, noscreen, nokeypad !default modes, 
input radix : decimal 
output radix: decimal 


DBOSHOW TYPE !Display current type, 

type: long integer 

DBODEPOSIT/WORD PSL = 0 !Disable all conditions in 

!PSL. In other words, 

!clear bits 0 thru 15. 

DBOEXAMINE PSL 

PSL: CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN Z V C 
0 0 0 0 USER USER 0 0 0 100000 


!Display formatted PSL. 
!A11 bits are cleared. 


6.3 The DEPOSIT Command 

You use the DEPOSIT command to deposit values in program locations. 

In the command format below, the expression designates the value to be 
deposited, and the address expression designates the program location into 
which the value is to be deposited. 

DEPOSIT [/qualifier] address-expression = expression [.expression...] 

The expression is evaluated in the syntax of the source language and in the 
default radix mode to yield a value. The address expression is evaluated to 
yield a program location with an associated type. 
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When the debugger executes the DEPOSIT command, it converts the value of 
the expression to the type associated with the address expression and deposits 
the value at the location designated by the address expression. 

You may specify a type command qualifier in the DEPOSIT command to 
associate a type with the program location denoted by the address expression. 

The following subsections discuss the depositing of numeric data, ASCII 
strings, and VAX instructions, as well as the use of radix and mode qualifiers 
in the DEPOSIT command. 


6.3.1 Depositing ASCII Strings 

You can deposit an ASCII string into a program location only if that location 
is denoted by an address expression with an associated ASCII type. 

Delimiters may be either apostrophes or quotation marks. However, the 
delimiter used cannot appear within the string itself. 

In all cases, if the length of the string to be deposited exceeds the length of 
the program location into which it is deposited, the debugger truncates the 
string to the length of the program location. On the other hand, if the length 
of the string is less than the length of the program location, the debugger 
inserts ASCII blanks in the remaining bytes of memory to the right of the last 
character in the string. 

The following sections discuss the depositing of ASCII strings into program 
locations denoted by address expressions that have an ASCII type, have a 
non-ASCII type, and have no type. 

Depositing with an ASCII type 

To deposit an ASCII string into a program location denoted by an address 
expression of ASCII type, issue the DEPOSIT command in the following 
format: 

DEPOSIT address-expression = "ASCII string" 

Depositing with a Non-ASCI I type 

If the program location is denoted by an address expression of a type other 
than ASCII, you can override that type by using the command SET TYPE 
/OVERRIDE ASCII:n. This procedure is especially useful when you intend to 
issue several DEPOSIT commands. 

You can also use the /ASCII:n command qualifier with the DEPOSIT 
command to override any associated type only for the duration of the 
command. This procedure is especially useful when you are issuing a single 
DEPOSIT command. 

The following command format demonstrates the use of the /ASCII:n 
command qualifier with the DEPOSIT command: 

DEPOSIT/ASCII:n address-expression « "ASCII string of length n" 

Note that the value n used in the command qualifier should normally 
correspond to the number of ASCII characters to be deposited, that is, to 
the length of the ASCII string. 

Example 6-22 demonstrates how to deposit ASCII strings. 
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Example 6-22 Depositing ASCII Strings 


DBODEPOSIT I = "GOOD" 

‘/.DEBUG - W -1N VNUMBER, invalid numeric string ’GOOD’ 


DBG>DEPOSIT/ASCII I = "GOOD" 

DBG>EXAMINE . 

T0Y\I: 1146048327 

DBOEXAMINE/ASCII . 

T0Y\I: "GOOD" 

DBG>SET TYPE/OVERRIDE ASCII 

DBODEPOSIT I = "GOOD" 

DBOEXAMINE I 

T0Y\I: "GOOD" 

DBOCANCEL TYPE/OVERRIDE 

DBOEXAMINE I 

T0Y\I: 1146048327 


!Debugger is expecting a 
Inumber because I has an 
!associated numeric type. 

!Override that type. 

!Use ASCII override type. 
{Debugger deposits the string. 

!Display in default type. 
•Specify ASCII display. 

!Specify ASCII override 
!type. 


!Display in ASCII override 
!type. 

I Cancel ASCII override type. 

!Compiler-generated type 
!overrides the default ASCII 
!type. 


6.3.2 Depositing Numeric Data 

Example 6-23 demonstrates how you can deposit three integer values into 
three memory locations. It also shows how to use the byte, word, and 
longword type command qualifiers on the DEPOSIT command. 


6.3.3 Depositing and Replacing VAX Instructions 

To deposit VAX instructions, the following command format may be used: 

DEPOSIT/INSTRUCTION address-expression = "VAX instruction" 

You must enclose the instruction in either apostrophes or quotation marks. 
Either delimiter may be used so long as it does not appear within the 
instruction string. The first and last delimiter must be the same. 

You must tell the debugger to interpret the delimited string as an 
instruction and not as an ASCII string. You do this either with the 
DEPOSIT/INSTRUCTION command or with the SET TYPE/OVERRIDE 
INSTRUCTION followed by any number of DEPOSIT commands (to execute 
the command repeatedly). 

Depositing VAX instructions is simple when you are depositing into successive 
memory locations because you can use the logical successor symbol to locate 
the address where the next instruction is to be deposited. Example 6-24 
demonstrates this technique. 
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Example 6-23 Depositing Numeric Data 


DBG>SHOW MODE !Display the current 

modes: nosymbolic, noscreen, nokeypad !default modes. 


input radix : decimal 
output radix: decimal 

DBODEPOSIT J = 333 
DBODEPOSIT R = 444 
DBODEPOSIT K = 555 

DBOEXAMINE . 

T0Y\K: 555 

DBOEXAMINE J 
T0Y\J: 333 

DBOEXAMINE |RETj 
T0Y\R: 444.0000 


DBOEXAMINE [RET! 

T0Y\K: 555 

DBOSHOW TYPE 
type: long integer 

DBOEVALU/ADDR . 

724 

DBODEPOSIT/BYTE . = 1 


DBG>E . 

724: 1280461057 


DBOE/BYTE . 

724: 1 

DBODEPOS IT/WORD . = 2 


DBOE/WORD . 

724: 2 

DBODEPOSIT/LONG 724 = 9999 


DBOE/LONG 724 
724: 9999 


!Deposit data in J, R, K. 


!Current entity is location 
Hast deposited into. 

!The value 333 is deposited 
!in J. 

!The value 444 is deposited 
!into the logical successor 
!of J, which is R. The type 
lassociated with R is used 
Sin display, not the default 
!type. 

SThe value 555 is deposited 
Sinto the logical successor 
!of R, which is K. 

!Display the default type. 

!Current location is 724. 

!Deposit the value 1 into 
Sthe byte of memory whose 
Saddress is 724. 

!Because the default type is 
Slong integer, 4 bytes are 
!examined. 

!Examine one byte only. 

!Deposit the value 2 into 
Sthe first two bytes (word) 

Sof the current entity. 

!Examine a word of the 
!current entity. 

!Deposit the value 9999 into 
!4 bytes (a longword) begin- 
Sning at virtual address 724. 

!Examine 4 bytes (longword) 

!beginning at virtual 
Saddress 724. 


Replacing one or more VAX instructions with new ones involves keeping 
track of the length of each instruction, which varies depending on the type of 
instruction and the number of operands. 

When you replace an instruction, you must ensure that the new instruction is 
the same length in bytes as the old instruction. 

If the new instruction is longer than the old instruction, you cannot deposit it 
without overwriting, and thereby destroying, the subsequent instruction. 
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Example 6-24 Depositing VAX Instructions 


DBG>SET TYPE INSTRUCTION 

DBODEPOSIT 730 = "MOVB #77, R1 


DBOEXAMINE 



730: MOVB 

#77, R1 


DBOEXAMINE 
734: HALT 

[RETl 


DBODEPOSIT 

. = "MOVB 

#66, R2" 

DBOEXAMINE 



734: MOVB 

#66,R2 


DBOEXAMINE 
738: HALT 

[RETl 


DBODEPOSIT 

. = "MOVB 

#55. R3" 

DBOEXAMINE 



738: MOVB 

#55,R3 



!Set default type to 
!instruction. 

!Deposit the instruction 
!beginning at virtual 
!address 730. 

!Examine current entity. 

!Make current entity the 
{logical successor of 
{virtual address 730. 

!Deposit next instruction 

{Examine current entity. 

{Make current entity the 
{logical successor of 
{virtual address 734. 

{Deposit next instruction 

{Examine current entity. 


If the new instruction occupies fewer bytes of memory than the old 
instruction, it can be deposited without overwriting previous or subsequent 
instructions; however, you must deposit NOP instructions (instructions 
that cause "no operation") in bytes of memory left unoccupied after the 
replacement. 

The debugger does not warn you if an instruction you are depositing will 
overwrite a subsequent instruction, nor does it remind you to fill in vacant 
bytes of memory with NOPs. Therefore, careful calculation of instruction 
length is required in replacing instructions. 

Example 6-25 demonstrates the replacing of an instruction with an instruction 
of equal length. 


6.3.4 Depositing in Different Radixes 

Literals in source-language expressions are interpreted by the debugger in the 
current radix mode or in the radix specified by a radix operator. Example 6-26 
demonstrates how to deposit literals in binary, decimal, hexadecimal, or octal 
radix. 


6.3.5 Depositing Values in Registers 

The rules for referring to registers are the same for both the DEPOSIT 
command and the EXAMINE command. See Section 6.2.6 for detailed 
information. 

Example 6-27 demonstrates how to examine and deposit values into the VAX 
registers. 


6-15 











Examining and Depositing Data 


6.3.5.1 


Example 6-25 Replacing VAX Instructions 


DBG>SET STEP INSTRUCTION 


!Set step unit to instruc¬ 
tion. 

DBG>STEP 

stepped to 1584: PUSHAL 

(Rll) 

{Step by instruction. 

DBG>STEP 

stepped to 1586: CALLS 

#1,L~2224 

!Step by instruction. 

{Replace this instruction. 

DBG>EXAMINE .PC 

1586: CALLS #1.L~2224 



DBG>EXAMINE |RET| 

1593: CALLS #0,L~2216 


•Subsequent instruction 
{begins at 1593. 

DBG>DEPOSIT/INSTRUCTION : 

L586 = "CALLS 

#2,L~2224" 

{Deposit new instruction. 

DBG>EXAMINE . 

1586: CALLS #2,L~2224 


!New instruction is 
{deposited. 

dbg>examine 1 ret) 

1593: CALLS #0,L~2216 


{Subsequent instruction is 
!unchanged. 

Example 6-26 Depositing in Different Radixes 

DBG>SHOW MODE 

modes: nosymbolic, noscreen, nokeypad 
input radix : decimal 
output radix: decimal 

{Display the current 
{default modes. 

DBG>SH0W TYPE 

type: long integer 


{Display default type. 

dboexamine j 

T0Y\J: 234567890 


{Display J in default 
{modes and type. 

DBODEPOSIT J = ‘/.OCT 7777777 

!Deposit an octal value. 

DBOEXAMINE . 

T0Y\J: 2097151 


{Display in compiler-generated 
{type and default radix 
!(decimal). 

dboexamine/octal . 

T0Y\J: 00007777777 


{Display in compiler-generated 
{type and octal radix. 

DBODEPOSIT J = '/.HEX 7777777 

{Deposit a hexadecimal 
!value. 

DBOEXAMINE . 

T0Y\J: 125269879 


{Display in type 
{associated with J and in 
{default radix (decimal). 

dboexamine/hex . 

T0Y\J: 07777777 


{Display in hexadecimal. 


The Processor Status Longword 

When you deposit into the PSL, your purpose is to enable or disable certain 
processor state conditions. Table 6-2 in Section 6.2.6.1 contains a list of the 
processor state conditions that you can manipulate. For more information on 
the PSL, refer to Section 6.2.6.1. 
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Example 6-27 Examining and Depositing Values in VAX 
Registers 


DBOSHOW MODE 

modes: nosymbolic, noscreen, nokeypad 
input radix : decimal 
output radix: decimal 

{Display the current 
{default modes. 

DBOSHOW TYPE 

type: long integer 

{Display current type. 

DBOEXAMINE SP 

SP: 2147278720 

{Examine value of the stack 
{pointer. 

DBODEPOSIT SP = 33 

!Deposit 33 into SP. 

DBOEXAMINE . 

SP: 33 

{Check the value of SP. 

DBOEXAMINE Rll 

Rll: 1024 

{Examine contents of Rll. 

DBODEPOSIT Rll = 444 

!Deposit new value into Rll 

DBOEXAMINE Rll 

Rll: 444 

{Check the value of Rll. 


Table 6-2 PSL Modification Values 


Bit 

Key 

Key Number 
(Hex) 

Description 

15 


0 

Must be zero 

14 


0 

Must be zero 

13 


0 

Must be zero 

12 


0 

Must be zero 

11 


0 

Must be zero 

10 


0 

Must be zero 

9 


0 

Must be zero 

8 


0 

Must be zero 

7 

DV 

80 

Decimal overflow trap enable 

6 

FU 

40 

Floating underflow trap enable 

5 

IV 

20 

Integer overflow trap enable 

4 

T 

10 

Trace trap condition code 

3 

N 

8 

Negative condition code 

2 

Z 

4 

Zero condition code 

1 

V 

2 

Overflow condition code 

0 

c 

1 

Carry condition code 
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To deposit a value into the PSL, determine which bits you want set; add their 
corresponding key numbers together; and use the sum as the "expression" in 
the command below: 

DBG>DEPOSIT/WORD PSL = '/.HEX (expression) 

Note: If you deposit into the high word of the PSL, bits 16 through 31, a 
reserved operand fault is generated when control is returned to your 
program by a STEP or GO command. 

Example 6-28 demonstrates how to examine and modify the PSL: 

Example 6-28 Examining and Modifying the PSL 


DBG>SHOW MODE !Display the current 

modes: nosymbolic, noscreen, nokeypad !default modes, 

input radix : decimal 
output radix: decimal 

DBG>SH0W TYPE !Display current type, 

type: long integer 

DBG>D EPOSIT/WORD PSL = 0 !Disable all conditions in 

!PSL. In other words, 

!clear bits 0 thru 15. 

DBG>EXAMINE PSL 

PSL: CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN Z V C 

0 0 0 0 USER USER 0 0 0 100000 

!Display formatted PSL. 
!A11 bits are cleared. 

DBG>DEP0S IT/WORD PSL = '/.HEX 80 !Key-number 80 from 

!Table 6--2 enables the 
!decimal overflow trap; 

!this is key "DV" in 
•the formatted display. 

DBG>EXAMINE PSL 

PSL: CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN Z V C 

0 0 0 0 USER USER 0 1 0 100000 

!Verify that the 
!DV bit is set. 


6.4 The EVALUATE Command 

The debugger interprets the operand of an EVALUATE command as a source- 
language expression, evaluates it in the semantics of the source language, and 
displays its value as a literal in the source language. 

The format of the EVALUATE command is 

EVALUATE [/qualifier] expression [.expression...] 

See Appendix A for detailed information about supported operators in 
language expressions for various languages. You can also obtain information 
by typing "HELP languages." 

If you specify a radix mode command qualifier, the debugger interprets 
any integer literals in the expression (or expressions) in the current radix. 
However, it displays the value of the expression (or expressions) in radix you 
specified with the command qualifier. 
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If you specify a radix operator, the debugger interprets integer literals in the 
expression (or expressions) in that radix. However, it displays the value of 
the expression (or expressions) in the current radix. 

If an expression contains symbols with different compiler-generated types, the 
debugger uses the type-conversion rules of the current language to evaluate 
the expression. 

You can evaluate more than one expression in a single EVALUATE command 
by separating expressions with a comma. 

Using the EVALUATE command, you can perform arithmetic calculations that 
may or may not be related to your program. You may also perform radix 
conversions by using radix mode command qualifiers or radix operators. 

Example 6-29 demonstrates how to use the EVALUATE command (language 
is set to FORTRAN). 

Example 6-29 Using the EVALUATE Command 


DBG>DEPOSIT R = 5.35E3 

DBOEVALUATE R 
5350.000 

DBOEXAMINE R 
T0Y\R: 5350.000 


DBOEVALUATE R*50 
267500.0 

DBOEVALUATE (R*50)/(540-40) 
535.0000 

DBODEPOSIT I = 22222 

DBOEVALUATE I 
22222 

DBOEVALUATE R/I 
0.2407524 

DBOEVALUATE 2.5*35 
87.50000 

DBOEVALUATE/OCTAL 17/2 
00000000010 

DBOEV ‘/.OCT 17/2 
00000000007 

DBOEVALUATE/HEX 17/2 
00000008 

DBOEV '/.HEX 17/2 
DBG>11 

DBOEVALUATE/HEX ‘/.HEX 17/2 
0000000B 


!R is of type floating point. 

!Gives the value of R. 

!The EXAMINE command is 
•similar. Note that symbolic 
!address of R is displayed. 

!Perform arithmetic 
!calculation. 

!Perform arithmetic 
!calculation. 

!Deposit value in I. 

!Note that I is of type 
!integer. 

!Expression is evaluated 
!in floating point. 

!Perform an arithmetic 
!calculation. 

!Octal qualifier affects 
!output, not input. 

!Octal operator affects 
!input, not output. 

!Hex qualifier affects 
!output, not input. 

!Hex operator affects 

!input, not output. 

!Both input and output 
!are interpreted in hex. 
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Displaying Source Code 


This chapter describes a source-language display feature that makes it possible 
(in some languages only) to display programming statements in the language 
in which the program was written. Such programming statements are referred 
to as source code. 

The debugger identifies a line of source code (a source line) by the line 
number assigned to it by the compiler. The compiler assigns a line number to 
each line of source code in the program in sequential order from the first to 
the last line. Line numbers appear on a compiler listing, which the compiler 
generates when the /LIST command qualifier is specified at compile time. 

The display of source lines is independent of program execution; that is, 
you may display source lines from any region of your program without such 
display affecting the value of the program counter (PC) or processor status 
longword (PSL). 

You can display source code by specifying any of the following forms of input 
parameter: 

• A compiler-assigned line number 

• An address expression that denotes a program location that has a 
corresponding line number 

• A source code string that identifies a source line by its appearance on that 
line 

It is also possible to display source lines along with other debugger display 
such as that resulting from the execution of a STEP command, a breakpoint 
hit, or a watchpoint hit. 

Section 7.1 describes how the debugger locates source files; it also describes 
how to direct the debugger to locate source files that have been moved to a 
different directory since being compiled. Sections 7.2 through 7.5 describe 
how to display source lines in each of the ways mentioned above. Section 7.6 
describes how to establish parameters that govern the display of source lines. 


7.1 Location of Source Files 

A source file is a file containing statements in a programming language. A 
compiler processes source files to generate object modules. If the /DEBUG 
qualifier is specified at compile time, the compiler generates source-line 
correlation records for inclusion in the debug symbol table (DST). 

Source-line correlation records contain the full file specification (that is, device 
name, directory name, file name, file type, and version number) of each 
source file that contributes to each object module, and they specify which 
source record in which source file corresponds to which line number in the 
object module. Source-line correlation records are passed to the linker and 
made available to the debugger at run time. 
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During a debugging session, therefore, the debugger need only refer to its 
DST to locate, for any object module, the source file containing the source 
lines that you want to display. 

However, if a source file has been moved to another directory since being 
compiled, the full file specification of the source file as listed in the DST 
record will no longer be correct, and the debugger will not be able to locate 
the source file using the DST record. In this case, you must direct the 
debugger to the current location of the source file by means of the SET 
SOURCE command. 

The availability of long filenames in Version 4.0 of VAX/VMS creates a 
problem with the "Declare Source File" command in the source correlation 
DST record. Both the DST record and the command within the record have 
byte fields to hold the length. However, a file specification can be as long 
as 252 characters, and together with the 20 bytes of other information in the 
DST record, this exceeds what can be stored in a byte length. In order to 
obtain source display, restrict the full file specification of the source file to 231 
characters. You can work around this problem by using the SET SOURCE 
command. For example, if you define a logical name "X" to expand to your 
long file specification, the "SET SOURCE X" will show the source display. 


7.1.1 SET, SHOW, and CANCEL SOURCE Commands 

If you have moved a source file to another directory, issue the SET SOURCE 
command in the following format: 

SET SOURCE[/M0DULE=modname] dirname[,dirname...] 

If you specify the optional /MODULE=modname command qualifier, the 
debugger looks in the specified directory or directories only when it is locating 
the source file(s) for the specified module. 

If you issue a SET SOURCE command without the /MODULE=modname 
command qualifier, the debugger looks in the specified directory or directories 
when it is locating the source file(s) for any module not mentioned in a 
previous SET SOURCE/MODULE=modname command. 

In sum, the SET SOURCE/MODULE command tells the debugger where to 
find source files for a particular module, whereas the SET SOURCE command 
tells the debugger where to find source files for modules that were not 
mentioned explicitly in SET SOURCE/MODULE commands. 

The dirname parameter may consist of one, several, or all fields in a full file 
specification, though usually it is only a directory name. The following is the 
format of a full file specification: 

node::device:[directory]file-name.file-type;version-number 

When specifying any of these fields, you must include the punctuation 
for that field, as shown in the above format. For example, to specify the 
relocation of source files to the directory NEWDIR on the disk NEWDISK, 
issue the following command: 

DBG>SET SOURCE NEWDISK:[NEWDIR] 

The debugger processes the dirname parameter by inserting the specified 
fields in the file specification of the source file as it appears in the DST. In 
this way, the debugger creates a new file specification, which it then uses to 
locate the source file. 
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When a source file is moved to another directory, the version number of the 
source file may change. Hence, to locate the correct version of the source 
file in the event that a version number was not specified in the dirname 
parameter, the debugger inserts the match-all wildcard character (*) in the 
version number field of the new file specification. As a result, all versions of 
the moved source file are searched until the correct version is located. The 
correct version of the source file is the version that has the same revision 
date and time, the same file size, the same record format, and the same file 
organization as the original compile-time source file. 

You can specify more than one dirname parameter in a single SET SOURCE 
command by separating each dirname parameter with a comma. In this case, 
the debugger constructs a new file specification for each dirname parameter 
specified and uses this list of file specifications to locate source files for the 
object module. Since the dirname parameter is most often a directory name, 
when you specify more than one dirname parameter in a single SET SOURCE 
command, you establish a source directory search list. 

When a source directory search list has been established for a module or 
modules, the debugger locates the source files for the designated modules by 
searching the first directory on the list, then the next, and so on, until it either 
locates the source file or exhausts the list. Using a source directory search list 
is particularly helpful when relocated source files are in several directories. 

The SHOW SOURCE command displays the source directory search lists 
currently in effect. The format of the SHOW SOURCE command is SHOW 
SOURCE. 

If a source directory search list has been established for all modules, the 
SHOW SOURCE command indicates the name(s) of each directory specified 
and indicates that the list applies to all modules. 

If a source directory search list has been established for one or more modules, 
the SHOW SOURCE command displays the name(s) of each directory 
specified and displays the name(s) of the module(s) to which the directory 
search list applies. 

If no source directory search list has been established, the SHOW SOURCE 
command indicates that no such list is currently in effect. 

The CANCEL SOURCE command cancels the effects of previous SET 
SOURCE commands. The format of the CANCEL SOURCE command is 

CANCEL SOURCE [/MODULE=modname] 

The CANCEL SOURCE command, without the /MODULE=modname 
command qualifier, cancels the effect of a previous SET SOURCE 
command, but does not cancel the effect of any previous SET SOURCE 
/MODULE=modname command. 

The CANCEL SOURCE/MODULE=modname command cancels the effect of 
a previous SET SOURCE/MODULE=modname command in which the same 
module name was specified; it does not cancel the effect of a previous SET 
SOURCE command or of a SET SOURCE/MODULE=modname command in 
which a different module name was specified. 

In all cases, when a source directory search list has been canceled, the 
debugger again expects the source files corresponding to the designated 
modules to be in the same directories they were in at compile time. 
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Assume that you write a VAX COBOL program with the file name 
TEST.COB;8 and that this program contains two modules MODA and MODB. 
Assume further that your default disk is DB4 and that, when you compile this 
program, your default is set to [ME.COBPROG], a subdirectory in which you 
always keep COBOL programs. At compile time, then, your source file has 
the full file specification 

DB4:[ME.COBPROG]TEST.COB;8 

Assume that you link your program with a VAX FORTRAN program, 
consisting of a single module CHECK, and that the full file specification 
of this program at compile time is 

DB4:[ME.FORPROG]CHECK.FOR;2 

When you run the program and want to display source lines, the 
debugger looks for the source lines of modules MODA and MODB in 
DB4:[ME.COBPROG]TEST.COB;8 and for the source lines of module CHECK 
in DB4:[ME.FORPROG]CHECK.FOR;2. 

Assume that you move TEST.COB to a new subdirectory [ME.TEST]. Now 
when you run the program and request the debugger to display source lines 
from MODA, the debugger looks in DB4:[ME.COBPROG]TEST.COB;8 but 
does not find the source file. 

To direct the debugger to the correct directories, you can establish a source 
directory search list by issuing the command 

DBG>SET SOURCE [ME.TEST],[ME.FORPROG] 

The debugger processes this command by substituting the directory 
name [ME.TEST] in the compile-time file specifications of the source files 
corresponding to MODA, MODB, and CHECK. As a result, the debugger 
would successfully locate the source files for modules MODA and MODB 
(because they were moved to this directory) but would not locate the source 
file for module CHECK (because it was not moved from its compile-time 
directory [ME.FORPROG]). However, after failing to find the source file for 
module CHECK in the directory [ME.TEST], the debugger would substitute 
the next directory in the source directory search list ([ME.FORPROG]) and 
would then successfully locate the source file there. 

Another way to direct the debugger to the correct directories is to issue the 
following two commands: 

DBG>SET S0URCE/M0DULE=M0DA [ME.TEST] 

DBG>SET S0URCE/M0DULE=M0DB [ME.TEST] 

The debugger processes these commands by inserting the directory 
name [ME.TEST] in the compile-time file specifications of the source files 
corresponding to MODA and MODB. Now whenever you request a display 
of source lines from MODA or MODB, the debugger locates the source file in 
DB4:[ME.TEST]TEST.COB. 

In this example, it is necessary to issue two SET SOURCE 
/MODULE=modname commands, rather than a single SET SOURCE 
command, because the program contains another module CHECK whose 
corresponding source file was not moved to the directory [ME.TEST]. As a 
result, the debugger continues to look in the original compile-time directory 
DB4:[ME.FORPROG]CHECK.FOR;2 when displaying source lines for module 
CHECK. 
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7.2 Display by Line Number 

The TYPE command allows you to display one or more source lines by 
specifying one or more compiler-assigned line numbers, where each line 
number designates a line of source code. 

The following is the format of the TYPE command: 

TYPE [ [modname\][line-number[:line-number] - 

[,[modname\]line-number[:line-number]...] ] 

If you specify a single line number, the debugger displays the source line 
corresponding to that line number. 

If you specify a list of line numbers, separating each with a comma, the 
debugger displays the source line corresponding to each of the line numbers. 

If you specify a range of line numbers, separating the starting and ending line 
numbers in the range with a colon, the debugger displays the source lines 
corresponding to that range of line numbers. 

You can read through all the source language statements in your program by 
specifying a range of line numbers starting from 1 and ending at a number 
equal to or greater than the largest line number in the program listing. 

After displaying a source line, you can display the next line by issuing a 
TYPE command without a line number, that is, by issuing a TYPE command 
and then pressing the RETURN key. You can then display the next line and 
successive lines by repeating this sequence, in this way reading through your 
source program one line at a time. 

You can specify a module name with the line numbers to indicate that the 
lines are located in that module. In this case, you enter the module name, a 
backslash (), and the line numbers, without intervening spaces. 

If you do not specify a module name with the line numbers, the debugger 
uses the current scope setting to determine which module to use. In this 
case, the current scope is either the first module designated in a SET 
SCOPE command or, if a SET SCOPE command was not issued, the module 
containing the current PC. 

Example 7-30 demonstrates how to use the TYPE command. 


7.3 Display by Address Expression 

By specifying the /SOURCE qualifier in the EXAMINE command, you can 
display the source line(s) corresponding to the location(s) designated by one 
or more address expressions. 

The debugger evaluates each address expression to derive a virtual address, 
determines which compiler-assigned line number corresponds to each virtual 
address, and then displays the source line(s) designated by the line number(s). 

The format of the EXAMINE command is 

EXAMINE[/qualifier[/qualifier]] - 

[address-expression[:address-expression]- 
[,address-expression[:address-expression] ...]] 

The format of the EXAMINE command allows you to specify 
• A single address-expression parameter 
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Example 7-30 Using the TYPE Command 


DBOTYPE 160 
module COBOLTEST 


160: START-IT-PARA. 


!Display the source line 
!designated by line 
!number 160. 


DBOTYPE I RET 1 
module COBOLTEST 


{Display the source line 
’ {following the last 

MOVE SCI TO ESO. {displayed source line. 


161: 


DBG>T 160:163 
module COBOLTEST 


161 

162 

163 


160: START-IT-PARA. 


MOVE SCI TO ESO. 
DISPLAY ESO. 

MOVE SCI TO ESI. 


{Display the range of source 
{lines corresponding to the 
{range of specified line 
{numbers. 


DBOTYPE C0B0LTEST\160,22:24 


{Display a single line 
{and a range of lines of 
{source code in a specified 
!module. 


module COBOLTEST 

160: START-IT-PARA. 


module COBOLTEST 

22: 02 SC2V2 PIC S99V99 
23: 02 SC2V2N PIC S99V99 
24: 02 CPP2 PIC PP99 


COMP VALUE 22.33. 
COMP VALUE -22.33. 
COMP VALUE 0.0012. 


• A list of address-expression parameters 

• A range of address-expression parameters 

• A list of ranges of address-expression parameters 

In each case, when you specify the /SOURCE qualifier, the debugger 
evaluates any specified address expression to determine its corresponding 
source line. 

If you specify a single address expression, the debugger evaluates the 
address expression to derive a virtual address, determines what line number 
corresponds to that virtual address, and then (as in the TYPE command) 
displays the source line designated by that line number. 

If you specify more than one address expression (that is, a list), with a 
comma separating each address expression, the debugger evaluates each 
address expression as described above and displays, for each specified address 
expression, a corresponding source line. 

If you specify two address expressions, separated by a colon, the debugger 
evaluates each address expression to derive a range of virtual addresses, 
determines which line numbers correspond to the range of addresses, and 
then displays the source lines designated by the line numbers. In this case, 
both addresses in the range must correspond to line numbers in the same 
module, and the first of the two line numbers must be less than or equal to 
the second. 

Example 7-31 demonstrates how to use the EXAMINE/SOURCE command. 
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Example 7-31 Using the EXAMINE/SOURCE Command 


dbg>ex/source /.pc 

! '/.DEBUG-W-NOSRCLIN, no source line for address 7FFF005C 


DBOEX/SOURCE .'/.PC 
module COBOLTEST 

162: DISPLAY ESO. 


DBG>EX/S0U 2150 

module COBOLTEST 

165: MOVE SCI TO ES2. 

DBOEX/SOURCE 2150:2200 

module COBOLTEST 

165: MOVE SCI TO ES2. 

166: DISPLAY ES2. 

167: MOVE SC2V2 TO ESO. 

168: DISPLAY ESO. 

169: MOVE SC2V2 TO ESI. 


I The address expression '/.PC 
!designates the address at 
!which the contents of the PC 
!is stored. There is no 
!source line corresponding to 
!this address. To get the 
!desired result, you must 
!specify the "contents of" 

!operator, the period (.), 
las shown in the following 
!command. 

IThis command displays the 
!source line corresponding 
!to the line containing 
!the PC. In effect, it 
!displays the source line 
{currently being executed. 

IThis command displays 
!the source line corresponding 
!to the virtual address 2150. 

IThis command displays the 
!range of lines of source 
I code that correspond 
•to the range of specified 
!virtual addresses. 


DBOEX/SOURCE 2100:2120,2150:2175 

module COBOLTEST 

161: MOVE SCI TO ESO. 

162: DISPLAY ESO. 

163: MOVE SCI TO ESI. 

module COBOLTEST 

165: MOVE SCI TO ES2. 

166: DISPLAY ES2. 

167: MOVE SC2V2 TO ESO. 


IThis command displays the 
Hist of ranges of source 
llines corresponding to 
I the list of ranges of 
!specified virtual addresses. 


7.4 Display During Program Execution 

When you specify either the SET STEP SOURCE command (the default) or 
the STEP/SOURCE command, the debugger displays source lines when any 
one of the following events occur: 

• You issue a STEP command and do not specify the /NOSOURCE 
qualifier. In this case, the debugger displays the source line following 
the last line or instruction executed. 

• A breakpoint or tracepoint is activated; in this case, the debugger displays 
the source line at the location of the eventpoint. 

• A watchpoint is activated; in this case, the debugger displays the 
source line corresponding to the instruction that caused the watchpoint 
activation. 

When you have given the SET STEP NOSOURCE command, the debugger 
does not display source lines when STEP commands are executed or when 
eventpoints are activated. 
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When you specify the /SOURCE or /NOSOURCE qualifiers on the STEP 
command, they override, for the duration of that STEP command, any 
specified or default source parameter currently in effect. However, as 
command qualifiers, /SOURCE and /NOSOURCE do not affect whether 
or not the debugger displays source lines when an eventpoint is being 
evaluated; they only affect whether or not the debugger displays source lines 
when STEP commands are executed. 

Thus, when the SOURCE parameter is in effect, specifying the /NOSOURCE 
command qualifier on the STEP command suppresses the display of source 
line(s) for the duration of that STEP command. The debugger continues to 
display source lines when eventpoints are activated or when subsequent STEP 
commands are executed (unless the /NOSOURCE command qualifier is again 
specified). 

Also, when the NOSOURCE parameter is in effect (whether by default or 
by an explicit SET STEP NOSOURCE command), specifying the /SOURCE 
command qualifier on the STEP command causes the debugger to display 
source line(s) for the duration of that STEP command. The debugger does 
not display source lines when eventpoints are activated or when subsequent 
STEP commands are executed (unless the /SOURCE command qualifier is 
again specified). 

However, you can specify the /SOURCE or /NOSOURCE command 
qualifiers on the SET BREAK, SET TRACE, and SET WATCH commands. 
These qualifiers override the current step setting while the eventpoint is 
evaluated; they do not permanently change the step setting. 

Example 7-32 demonstrates how to display lines of source code during 
program execution. 
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Example 7-32 Displaying Source Code During Program 
Execution 


DBG>STEP 

stepped to COBOLTEST\START-IT 
161: MOVE SCI TO ESO. 


DBG>SET BREAK ‘/.LINE 163 


{Execute a line of code. 

{Since the default SOURCE 
{parameter is in effect, the 
{debugger displays the source 
{line. 

{Set a breakpoint at 
{line number 163. 


DBG>GO 

break at COBOLTEST\START-IT\START-IT-PARA\7,LINE 163 
163: MOVE SCI TO ESI. 


DBG>SET BREAK/NOSOURCE ‘/.LINE 164 


{Begin execution at the 
{current location. Source 
{line display occurs when 
{the breakpoint is reached 

!Set a breakpoint at 
{line number 164. Specify 
{that the source lines are 
Snot to be displayed. 


DBG>G0 

break at COBOLTEST\START-IT\START- IT-PARAV/.LINE 164 

{Begin execution at the 
{current location. The 
{source code is not dis¬ 
played although SOURCE 
{is the current step setting. 


DBG>SET BREAK ’/.LINE 165 


DBG>SET STEP NOSOURCE 


!Set a breakpoint at 
{line number 165. 

{Specify that source lines 
!not be displayed when STEP 
{commands are executed or 
{when breakpoints or 
{watchpoints are activated. 


DBG>G0 

break at COBOLTEST\START-IT\START 


DBG>STEP/SOURCE 

stepped to COBOLTESTV/.LINE 166 
166: DISPLAY ES2. 


DBG>STEP 

stepped to COBOLTESTV/.LINE 167 


IT-PARA\y,LINE 167 

{Begin execution at the 
{current location. Note that 
!a source line is not 
{displayed at breakpoint 
{activation because NOSOURCE 
!is in effect. 

{Execute a line of code and 
'.display the source line 
{following the line executed. 
!The NOSOURCE parameter is 
{overriden for the duration 
!of the STEP command. 

{Execute a line of code. 

{Note that no source code 
{is displayed because the 
!SET STEP NOSOURCE command 
!was issued and the /SOURCE 
{qualifier was not specified 
!in the STEP command. 
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7.5 Display by Search String 

The SEARCH command directs the debugger to search the source code 
for a specified string and to display the source line or lines containing an 
occurrence of the string. 

The format of the SEARCH command is 

SEARCH [/qualifier,...] range string 

The range parameter limits the debugger's search for occurrences of the string 
to specified regions of the source code. These regions may be specified in any 
of the following formats: 

MODNAME Indicates a search of the specified module 

from line number 0 to the end of the 
module. 

MODNAME\LINE-NUM Indicates a search of the specified module 

from the specified line number to the end of 
the module. 

Indicates a search of the specified module 
beginning at the line number specified to 
the left of the colon and ending at the line 
number specified to the right of the colon. 

Indicates a search of the module designated 
by the current scope setting from the 
specified line number to the end of the 
module. 

Indicates a search of the module designated 
by the current scope setting beginning at 
the line number specified to the left of the 
colon and ending at the line number to the 
right of the colon. 

Indicates a search of the same module as 
that from which a source line was most 
recently displayed (as a result of a SEARCH, 
TYPE, or EXAMINE/SOURCE command), 
beginning at the first line following the line 
most recently displayed and continuing to 
the end of the module. 

The string parameter specifies the source code characters for which to search. 
If the string parameter is not specified, the debugger uses the last specified 
search string, that is, the string parameter specified in the last SEARCH 
command. If there was no previous search string, an error message results. 
The string parameter may be enclosed in quotation marks or in apostrophes 
or may be specified without delimiters. 

If the string contains a quotation mark and you want to delimit the string 
with quotation marks, use double quotation marks to indicate the quotation 
mark that is part of the string. Likewise, if the string contains an apostrophe 
and you want to delimit the string with apostrophes, use double apostrophes 
to indicate the apostrophe that is part of the string. 


UNE-NUM:LINE-NUIVI 


NULL 


MODNAME\LINE-NUM:LINE-NUM 


LINE-NUM 
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A delimited string may contain spaces, tabs, or special characters. Specifying 
an undelimited string is more convenient because it saves keystrokes, but an 
undelimited string is subject to certain restrictions: 

• It must have no leading or trailing blanks or tabs. 

• It must have no embedded semicolon (;). 

• The range parameter must not be null; that is, an explicit range must be 
specified. 

The /ALL command qualifier directs the debugger to search for all 
occurrences of the string in the specified range and display every line 
containing an occurrence of the string. 

The /NEXT command qualifier directs the debugger to search for the first 
occurrence of the string in the specified range and to display only the line 
containing this occurrence. Subsequent lines in the specified range that 
contain the search string are not displayed. /NEXT is the default. 

The /IDENTIFIER command qualifier directs the debugger to search for an 
occurrence of the string in the specified range but to display the string only if 
it is bounded on either side by a character that cannot be part of an identifier 
in the current language. (An identifier is the name associated with a data or 
program entity.) 

Specifying /IDENTIFIER is useful when you are searching for an identifier 
but want to eliminate extraneous occurrences of the character(s) composing 
that identifier. For example, suppose you want to display all occurrences 
of the identifier X, but your program also contains identifiers XT and EXP. 
Obviously, you do not want every occurrence of XT and EXP to be displayed 
just because it contains the character X. So you specify the /IDENTIFIER 
command qualifier to direct the debugger to disregard occurrences of XT and 
EXP. The debugger disregards them because the X in both XT and EXP is 
bounded on at least one side by a character (a letter of the alphabet) that can 
be part of an identifier in the current language. 

The /STRING command qualifier directs the debugger to search for and 
display the string as specified, and not to interpret the context surrounding an 
occurrence of the string, as it does in the case of /IDENTIFIER. /STRING is 
the default. 

The SET SEARCF1 command establishes current SEARCH parameters for the 
debugger to use whenever a SEARCH command qualifier is not specified 
in a SEARCH command. The following is the format of the SET SEARCH 
command: 

SET SEARCH parameter[.parameter] 

SEARCH parameters determine whether the debugger searches for all 
occurrences (ALL) of the string or only the next occurrence (NEXT) of the 
string, and whether the debugger displays any occurrence of the string 
(STRING) or only those occurrences in which the string is not bounded on 
either side by a character that can be part of an identifier in the current 
language (IDENTIFIER). 

If you do not specify SEARCH parameters with the SET SEARCH command, 
the debugger uses the default values NEXT and STRING. 

You can override current SEARCH parameters for the duration of a single 
SEARCH command by specifying other SEARCH parameters as command 
qualifiers in the SEARCH command. 
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You can specify more than one SEARCH parameter in a single SET SEARCH 
by separating parameters with a comma. 


The SHOW SEARCH command displays the current SEARCH parameters. 

Example 7-33 demonstrates how to use the SEARCH, SET SEARCH, and 
SHOW SEARCH commands: 

Example 7-33 Using the SEARCH and SET/SHOW SEARCH 
Commands 


DBG>SHOW search 
search settings: 


search for next occurrence, as a string 

!Display current SEARCH 
!parameters. 


DBG>SEARCH/STRING/ALL 40:50 D 
module C0B0LTEST 


40: 

02 

D2N 

COMP-2 

VALUE 

-234560000000. 

41: 

02 

D 

COMP-2 

VALUE 

222222.33. 

42: 

02 

DN 

COMP-2 

VALUE 

-222222.333333. 

47: 

02 

DRO 

COMP-2 

VALUE 

0.1. 

48: 

02 

DR5 

COMP-2 

VALUE 

0.000001. 

49: 02 

DR10 

COMP-2 

VALUE 

0.00000000001. 

50: 02 

DR15 

COMP-2 

VALUE 

0.0000000000000001 


!Display all source lines 
!in the range of line numbers 
!40 to 50 that contain an 
!occurrence of the letter D. 

DBG>SEARCH/IDENTIFIER/ALL 40:50 D 
module C0B0LTEST 

41: 02 D COMP-2 VALUE 222222.33. 

!Display a line containing D 
lonly if D is bounded on 
Iboth sides by a character 
Ithat cannot be part of an 
!identifier in the current 
!language. 

DBG> SEARCH/NEXT 40:50 D 
module COBOLTEST 

40: 02 D2N COMP-2 VALUE -234560000000. 

!Display the first occurrence 
!of D in the range. 

dbg>search/next 

module COBOLTEST 

41: 02 D COMP-2 VALUE 222222.33. 

!Display the first occurrence 
!of D (the previous search) 

!string in the range begin¬ 
ning at the line following 
!the last line displayed 
!(line 40 in the above com-) 
!mand and ending at the end 
!of the current module. 





(Continued on next page) 
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Example 7-33 (Cont.) 


Using the SEARCH and SET/SHOW 
SEARCH Commands 


DBG>SEA 80:90 
module C0B0LTEST 

80: 02 LS10 PIC S9(10) LEADING SEPARATE VALUE 

-: 1234567890. 

!Display all occurrences of D 
!(the previous search string) 
!in the range 80:90. Note 
!that the line wraps. 

DBG>SEA C0B0LTEST\17O ’D’ 

module COBOLTEST 

170: DISPLAY ESI. 

!Display the first occurrence 
!of D in the module COBOLTEST 
!in the range beginning at 
!line 170 and ending at the 
lend of the module. 

DBG>SEA C0B0LTEST\15O * E’ 

module COBOLTEST 

161: MOVE SCI TO ESO. 

!Display the first occurrence 
!of the delimited string in 
!the module COBOLTEST in the 
!range beginning at line 150 
land ending at the end of 
Ithe module. 

DBG>SEARCH/NEXT IV" 

module COBOLTEST 

2: PROGRAM-ID. COBOLTEST. 

1 Display the first occurrence 
lof the delimited string in 
Ithe module COBOLTEST in the 
1 range beginning at line 1 
land ending at the end of 
Ithe module. 

DBG>SET SEARCH IDENT ISet the current SEARCH 

1 parameter to IDENTIFIER. 

DBG>SH0W SEARCH 

search settings: search for next occurrence, as an identifier 

{Display current SEARCH 
1 parameters 

DBG>SET SE AL ISet the current SEARCH 

1 parameter to ALL. 

DBG>SH SEA 

search settings: search for all occurences, as an identifier 

{Display current SEARCH 
{parameters. 


7.6 Source Display Parameters 

This section describes parameters to set margins on the display of source code 
and to limit the number of source files that the debugger may keep open at 
any one time. 
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7.6.1 Margin Parameters 

The SET MARGINS command specifies the leftmost source-line character 
position at which to begin display of a source line (the left margin) and/or 
the rightmost character position at which to end display of a source line. 

By default, the debugger displays a source line beginning at character position 
1 of the source line. Source-line character position 1 is actually character 
position 9 on your terminal screen. The first eight character positions on the 
terminal screen are occupied by the line number and cannot be manipulated 
by the SET MARGINS command. 

Increasing the left margin setting (from its default value of 1) is particularly 
useful when the source code is deeply indented; by eliminating the display of 
empty space, more space is available on the terminal line for the display of 
source code. 

Decreasing the right margin setting from its default value of 255 prevents 
wrapping of long lines by truncating them. Since a wrapped line of source 
code requires two lines on the terminal, eliminating wrapping allows more 
lines of source code to be displayed on the terminal screen. 

The SET MARGINS command affects only the display of source lines, that is, 
the display resulting from commands such as TYPE and EX AMINE/SOURCE. 
The SET MARGINS command does not affect the display resulting from 
commands (such as EXAMINE, EVALUATE, SHOW MODE, and so on) that 
do not display source code. If a command displays source code together with 
other information—as, for example, STEP/SOURCE does—the display 
of source code is affected by the current margin settings but the other 
information is not. 

The following is the format of the SET MARGINS command: 

rm 

SET MARGINS lm:rm 
lm: 

:rm 

If you specify a single number, the debugger sets the left margin to 1 and the 
right margin to the number specified. 

If you specify two numbers, separated with a colon, the debugger sets the left 
margin to the number specified to the left of the colon and the right margin 
to the number specified to the right of the colon. 

If you specify a single number followed by a colon, the debugger sets the left 
margin to the number specified and leaves the right margin unchanged. 

If you specify a colon followed by a single number, the debugger sets the 
right margin to the number specified and leaves the left margin unchanged. 

The SHOW MARGINS command displays the current margin settings for the 
display of source lines. 

Example 7-34 demonstrates how to use the SET MARGINS and SHOW 
MARGINS commands. 
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Example 7-34 Using the SET/SHOW MARGINS Commands 


DBG>SH0W MARGINS 

left margin: 1 , right margin: 


255 

•Display current margin 
!settings. 


DBG>TYPE 116 
module COBOLTEST 

116: 02 RA26 PIC A(26) JUST RIGHT VALUE 

-: "ABCDEFGHIJKLMNOPQRSTUVWXYZ". 


DBG>SET MARGINS 50 


DBG> SHOW MARGINS 

left margin: 1 , right margin: 50 


DBG>TY 116 
module COBOLTEST 

116: 02 RA26 PIC A(26) 


DBG> SET MARGINS 10:60 


DBG>TY 116 
module COBOLTEST 

116: A26 PIC A(26) 


DBG>SET MARGINS :100 


!Display source line 116. 
INote that the line wraps, 
Ithus requiring two terminal 
Hines for its display. 

!Set the left margin to 1 
land the right margin to 50. 


!Display current margin 
!settings. 


JUST RIGHT VALUE 
•With a right margin of 50, 

!characters on source line 116 
!at positions greater than 50 
lare not displayed. As a 
!result, line 116 does not 
!wrap. 

!Set left margin to 10 and 
!right margin to 60. 


JUST RIGHT VALUE "ABCDEFGHI 

!Characters on source line 116 
!at positions less than 10 or 
!greater than 60 are not 
!displayed. 

ISet right margin to 100 and 
!leave left margin unchanged. 


(Continued on next page) 
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Example 7-34 (Cont.) Using the SET/SHOW MARGINS 

Commands 


DBOSHOW MARGINS 

left margin: 10 , right margin: 100 

!Display current margin 
!settings. 

DBG>SET MARGINS 5: !Set left margin to 5 and 

Heave right margin unchanged. 

DBOSHOW MARGINS 

left margin: 5 , right margin: 100 

{Display current margin 
!settings. 


7.6.2 Maximum Source Files Parameter 

The SET MAX—SOURCE—FILES command specifies the maximum number 
of source files that the debugger may keep open at any one time. 

The format of the SET MAX—SOURCE—FILES command is 

SET MAX.SOURCE.FILES n 

The parameter n is a decimal integer whose value designates the maximum 
number of source files that the debugger may keep open at any one time. 
The value of n may not exceed 20. The default value is 5. 

Opening a source file requires the use of an I/O channel, which is a limited 
system resource. Both the program and the debugger use I/O channels. To 
ensure that the debugger does not use all available I/O channels and thus 
cause the user program to fail (for lack of an available I/O channel), you 
can issue the SET MAX—SOURCE—FILES command to specify the maximum 
number of source files (and thus source file I/O channels) that the debugger 
may use at any one time. 

Note that the value of MAX—SOURCE—FILES does not limit the number 
of source files that the debugger can open; rather, it limits the number that 
may be kept open at any one time. Thus, if the debugger reaches this limit, it 
must close a file in order to open another one. 

Note too that setting MAX—SOURCE—FILES to a very small number can 
make the debugger's use of source files inefficient. 

The SHOW MAX—SOURCE—FILES command displays the number of source 
files that the debugger may keep open at any one time. 

Example 7-35 demonstrates how to use the SET MAX—SOURCE—FILES and 
SHOW MAX-SOURCE-FILES commands. 
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Example 7-35 Using the SET/SHOW MAX_SOURCE_FILES 
Commands 


DBOSHOW MAX.SOURCE.FILES 
max.source.files: 5 


DBG>SET MAX.SOURCE.FILES 8 


DBOSHOW MAX.SOURCE.FILES 
max.source.files: 8 


!Display the number of source 
Ifiles that the debugger may 
!keep open at the present 
!time. 

!Set the number of source 
Ifiles that the debugger may 
Ikeep open at any one time 
!to 8. 

!Verify the change. 


7.7 Differences Between Source and Object Code Due to 
Optimization 


When debugging with source code, you should keep in mind that, in general, 
there is no precise one-to-one correspondence between your source code and 
the compiler-generated object code. 

Most compilers optimize the object code they produce so that the program 
will execute faster. One method of optimizing object code is to perform 
operations in a sequence different from the sequence specified in the source 
code. 

As a result, the source code displayed by the debugger will not correspond 
exactly to the actual object code being executed. This is important to keep in 
mind, especially when using the SET STEP SOURCE, STEP/SOURCE, and 
EXAMINE/SOURCE commands. 

To illustrate, the following example depicts a segment of source code from 
a FORTRAN program as it would appear on a compiler listing. This code 
segment sets the first ten elements of array A to the value 1 /X. 

line source code 


5 DO 100 1=1,10 

6 A(I) = 1/X 

7 100 CONTINUE 

As the compiler processes the source program, it determines that the 
reciprocal of X need only be computed once, not ten times as the source 
code specifies, since the value of X never changes in the DO-loop. The 
compiler thus generates optimized object code equivalent to the following 
code segment: 

line object code equivalent 

5 T = 1/X 

DO 100 1=1,10 

6 A(I) = T 

7 100 CONTINUE 

In the optimized object code, the value of 1/X is computed once, saved in 
a temporary location, and then assigned to each A(I). The object code now 
executes faster, but it no longer corresponds exactly to the source code. 


7-17 











Displaying Source Code 


In this example, if you step to line 5 by issuing STEP/SOURCE (or SET 
STEP SOURCE followed by STEP), the debugger displays the source line as 
it appears in the source file, not the optimized object code equivalent that it is 
actually executing. 

stepped to PROG_V/,LINE 5 

5: DO 100 1=1,10 

At this point, if you issue another STEP command to execute line 5, the 
debugger executes line 5 of the optimized object code, not line 5 of the 
displayed source code. Thus, the program computes the reciprocal of X and 
sets up the DO loop, whereas the source display indicates only that the DO 
loop is set up. 

This discrepancy is not obvious from looking at the displayed source line. 
Furthermore, if the computation of 1/X were to fail because X is zero, it 
would appear from inspecting the source display that a division by zero had 
occurred on a source line that contains no division at all. 

This kind of apparent mismatch between source code and object code should 
be expected from time to time when debugging optimized programs. It can be 
caused not only by "code motions" out of loops, as in the above example, but 
by a number of other optimization methods as well. Optimization can cause 
segments of object code to move long distances from their original source 
code locations. 

If you should encounter a program segment where source and object code 
do not seem to match, you can inspect the object code itself by using 
the EXAMINE/INSTRUCTION or STEP/INSTRUCTION commands. 
Alternatively, you can inspect a compiler-generated machine code listing. 
Using either of these methods, you should be able to determine what is 
happening at the object code level and thereby resolve the discrepancy 
between source line display and program behavior. 

In addition, most languages allow you to specify the /NOOPTIMIZE 
command qualifier at compile time. Specifying this qualifier inhibits compiler 
optimization, thereby eliminating discrepancies between source code and 
object code caused by optimization. 
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Screen mode lets you see more information more conveniently than the 
default, line-oriented, display mode. In screen mode, you display different 
types of data in separate areas of the screen. You might, for example, display 
your source code in the top left half of the screen, the contents of the VAX 
registers in the top right half, debugger output in the middle, and diagnostic 
messages at the bottom, near your interactive input. 

To enable screen mode, press keypad key PF3 (or type the command SET 
MODE SCREEN). To return to line-oriented debugging, press GOLD-PF3 (or 
type the command SET MODE NOSCREEN). 

Screen mode output is best displayed on VT100 or VT200 series terminals and 
Micro VAX workstations. The ability to have many displays on the screen for 
different purposes is particularly useful with the larger screen of Micro VAX 
workstations. You can use screen mode with VT52 terminals, but they are 
less suited to the formatted screen displays since they do not support the 
scrolling regions used in screen mode. 

This chapter covers the following topics: 

• Section 8.1 introduces screen mode concepts and terminology used 
throughout the chapter. 

• Section 8.2 describes the predefined displays SRC, OUT, PROMPT, INST, 
and REG, which are automatically available when you enter screen mode. 

• Section 8.3 describes how to scroll, hide, delete, move, and resize a 
display. 

• Section 8.4 explains how to create a new display. 

• Section 8.5 explains how to specify a display window. 

• Section 8.6 describes the different kinds of displays and how to use them. 

• Section 8.7 explains how to direct various types of debugger output to 
different displays by assigning display attributes. 

• Section 8.8 gives an example of a display configuration to illustrate a 
possible use of screen mode. 

• Section 8.9 explains how to save the current state of your screen displays. 

• Section 8.10 explains how to change your terminal screen's height and 
width during a debugging session and describes how display windows 
behave when you change the height or width. 

Many screen mode commands are bound to keypad keys. See Appendix B 
for key definitions. Also, Appendix C contains screen mode information in 
summary reference format. 
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8.1 Concepts and Terminology 

A display is a group of text lines. The text may be lines from a source file, 
assembly language instructions, the values contained in registers, your input 
to the debugger, various types of debugger output, or program input and 
output. 

You view a display through its window , which may occupy any rectangular 
area of the screen. Because a display's window is typically smaller than 
the display, you can scroll the window up, down, right, and left across the 
display text to view any part of the display. 

The following example of screen mode shows three displays. The name of 
each display (SRC, OUT, and PROMPT) appears at the top left comer of its 
window. It serves both as a tag on the display itself and as a name for future 
reference in commands. 

• Display SRC is a source code display (displaying FORTRAN code in this 
example). SRC's current window is the upper half of the screen. Like 
other display windows, SRC's window may be changed to accommodate 
different display layouts. The name of the module whose source code is 
displayed, FORSQUARE$MAIN, is to the right of the display name. 

• Display OUT, located in a window directly below SRC, shows the output 
of debugger commands. 

• Display PROMPT, at the bottom of the screen, shows the debugger 
prompt and debugger input. 

SRC, OUT, and PROMPT are three of the five predefined displays that the 
debugger provides by default when you enter screen mode. You can create 
additional displays. 


- SRC: module 
7: C 
8 : 

9: 

10 : 

-> 11 : 

12 : 

13: 10 

14: C 
15: C 


FORSQUARE$MAIN -scroll-source 

-Square all non-zero elements and store in output array 

K s 0 

DO 10 I = 1, N 
IFUNARR(I) .NE. 0) THEN 

OUTARR(K) = INARR(I)**2 
ENDIF 
CONTINUE 

-Print the squared output values. Then stop. 


- OUT -output- 

stepped to FORSQUARE$MAIN\*/,LINE 9 
9: DO 10 I = 1. N 

FORSQUARE$MAIN\N: 9 

FORSQUARE$MAIN\K: 0 

stepped to FORSQUARE$MAIN\%LINE 11 


- PROMPT -error-program-prompt 
DBG> EXAM N. K 
DBG> STEP 2 
DBG> 


Every display has a memory buffer, whose size is independent of the 
window size and may be adjusted. Displays that hold source code or 
assembly language instructions let you see all of the lines of source code 
of the associated module or all of the instructions of the associated routine, 
regardless of the size of the memory buffer. This is because the necessary 
information is paged into the buffer as needed. For other displays, such as 
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display OUT, the buffer size defines how much text the display will hold. If 
you add more text to the display, the oldest text lines are discarded to make 
room for the new text. 

Conceptually, displays are placed on the screen as on a pasteboard. The 
display that is most recently referenced in a command is put on top of the 
pasteboard, by default. Therefore, depending on the window locations, the 
displays that you have referenced recently may overlay or hide other displays 
(as on a pasteboard). 

The debugger maintains a display list, which is the pasting order of displays. 
Several keypad key definitions use the display list to cycle through the 
displays currently on the pasteboard. 

Every display belongs to a display kind. The display kind determines what 
type of information the display can capture and/or display; for example, 
source code, assembly language instructions, debugger output of various 
types. The display kind also determines how the contents of the display are 
generated. 

In general, there are two ways in which the contents of a display are 
generated. Some displays are automatically updated. Their definition 
includes a command list that is executed whenever the debugger gains 
control from the program. The output of the command list forms the contents 
of those displays. Display SRC belongs to that category: the source display 
is automatically updated so that an arrow centered in the window shows the 
current location of the program counter. 

Other displays, for example display OUT, derive their contents from 
commands you issue interactively. If you create a display of this general 
category, you must first select it (with the SELECT command) as the target 
display for one or more types of output before anything can be written to it. 
This is also known as assigning one or more attributes to a display. 

The names of any attributes assigned to a display appear to the right of 
the display name, in lowercase letters. In the preceding example, SRC has 
the source and scroll attributes (SRC is the current source display and the 
current scrolling display), OUT has the output attribute (it is the current output 
display), and so on. Note that, although SRC is automatically updated by its 
own built-in command, it can also receive the output of certain interactive 
commands (such as EXAMINE/SOURCE) because it has the source attribute. 

The concepts introduced in this section are developed in more detail in the 
rest of this chapter. 


8.2 The Predefined Displays 

The debugger provides the following predefined displays by default: 

• A source display named "SRC" 

• An output display named "OUT" 

• A prompt display named "PROMPT" 

• An assembly-language instruction display named "INST" 

• A register display named "REG" 
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When you enter screen mode and the language is set to any language except 
MACRO, the debugger puts SRC in the top half of the screen, PROMPT in 
the bottom sixth, and OUT between SRC and PROMPT, as illustrated in 
Section 8.1. 

Each of the predefined displays is discussed in the next sections. 


8.2.1 The Predefined Source Display SRC 


Note: The debugger does not provide source line display for MACRO. If the 
language is set to MACRO, SRC is marked as removed (see Section 8.3.2) 
from the display pasteboard and is not visible. The INST display is put 
in its place. 

The predefined source display SRC displays the source code of the module 
being debugged, if that source code is available. The arrow in the leftmost 
column indicates the current PC location. Each time the debugger gains 
control from your program, the arrow position is updated, and the source text 
scrolls as needed so that the display is centered around the PC location. 

By default, SRC has the source attribute and, therefore, also shows the output 
of a TYPE or EXAMINE/SOURCE command (the source text is scrolled as 
needed to reveal the source line output). 

If source lines are not available for the currently executing routine (because, 
for example, the routine is a run-time library routine), the debugger attempts 
to display source lines in the caller of that routine (scope 1). If source lines 
are also not available at that level, the debugger tries scope 2, and so on. 
When displaying source lines that are not associated with the executing 
module, the debugger displays a message to that effect: 

'/.DEBUG -1 - SOURCESCOPE, Source lines not available for .OV/.PC. 

Displaying source in a caller of the current routine. 

The following example illustrates this feature. In the source display, the 
arrow indicates that the PC is at a call of routine TYPE. TYPE corresponds 
to a FORTRAN run-time library procedure. No source lines are available for 
that code, so the debugger displays lines in the caller of that routine. The 
output of a SHOW CALLS command, shown in the output display, identifies 
the currently executing module and the call sequence. 
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- SRC: module TEST -scroll-source-I 

'/.DEBUG-1 - SOURCESCOPE, Source lines not available for .OV/.PC I 

Displaying source in a caller of the current routine I 

3: CHARACTER*(*) ARRAYX I 

-> 4: TYPE *. ARRAYX I 

5: RETURN I 

6: END I 


- OUT --output- 

stepped to SHARE$F0RRTL+810 
module name routine name 

line 

rel PC 

abs PC 

SHARE$FORRTL 

SHARE$FORRTL 


0000032A 

00000B2A 

♦TEST 

TEST 

4 

000000IE 

00000436 

*A 

A 

3 

00000011 

00000411 


- PROMPT -error-program-prompt 

DBG> STEP 

DBG> SHOW CALLS 

DBG> 


8.2.2 The Predefined Output Display OUT 

By default, the predefined display OUT has the output attribute and therefore 
displays any debugger output that is not directed to the source display SRC 
or the instruction display INST. By default, OUT does not display debugger 
diagnostic messages (these appear in the PROMPT display). 

The preceding examples illustrate some typical debugger output in display 
OUT. You can assign attributes to OUT so it will capture debugger input and 
diagnostics as well as normal output (see Section 8.7). 


8.2.3 The Predefined Prompt Display PROMPT 

The predefined display PROMPT is where the debugger prompts for input. 
The preceding examples show PROMPT in its default location, the bottom 
sixth of the screen. 

By default, PROMPT has the program and error attributes, in addition to the 
prompt attribute. Therefore, the debugger forces program output to PROMPT 
and prints diagnostic messages to that display. 

PROMPT has different properties and restrictions than other displays. This is 
to eliminate possible confusion when manipulating that display: 

• The debugger always keeps PROMPT on top of the display pasteboard 
so it cannot be hidden by another display. You cannot hide PROMPT 
(with the DISPLAY/HIDE command), or remove PROMPT from the 
pasteboard (with the DISPLAY/REMOVE command), or permanently 
delete PROMPT (with the CANCEL DISPLAY command). 

• PROMPT can have the scroll attribute, so that it can be made the default 
target display for the MOVE and EXPAND commands. But you cannot 
scroll PROMPT. 
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• You can move PROMPT anywhere on the screen, expand it to fill the 
full screen height, and contract it down to two lines. But PROMPT must 
always occupy the full width of the screen. Therefore, you cannot move, 
expand, or contract PROMPT horizontally. 

The debugger alerts you if you try to move or expand a display where it will 
be hidden by PROMPT. 


8.2.4 The Predefined Instruction Display INST 

The predefined assembly-language instruction display INST displays the 
instruction stream of the routine being debugged (see the example that 
follows). The instructions displayed are decoded from the image being 
debugged. The numbers to the left of the instructions are line numbers. The 
arrow points to the instruction at your current PC. Each time the debugger 
gains control from your program, the arrow position is updated and the 
display is centered around the PC location. 

If the language is set to a language other than MACRO, INST is marked as 
removed (see Section 8.3.2) from the display pasteboard and is not visible. 
You need to use the DISPLAY command (or keypad keys 7 or GOLD-7) to 
show the INST display in such cases. If the language is set to MACRO, the 
INST display takes the place of the SRC display and is shown by default. 

If you assign the instruction attribute to INST with the command SELECT 
/INSTRUCTION INST, then the output of an EXAMINE/INSTRUCTION 
command will be directed to the instruction display. 

I- INST: routine FORSQUARE$MAIN.I 


1 


BLEQ 

FORSQUARE$MAIN\'/.LINE 16 

(Line 

10 

MOVL 

B~4(R11),R0 

1 


TSTL 

W~-164(R11)[RO] 

1 


BEQL 

FORSQUARE$MAIN\*/,LINE 13 

1 ->ne 

11 

MOVL 

B~12(R11),R1 

1 


MOVL 

B~4(R11).RO 

1 


MULL3 

VT-164(R11)[RO],W~-164(R11)[RO],B~-84(R11)[Rl] 

iLine 

13 

AOBLEQ 

B~16(R11) ,B~4(R11) ,FORSQUARE$MAINV/.LINE 10 

iLine 

1- OUT 

16 

-out] 

PUSHAL 

5Ut- 

L~525 


I stepped to F0RSQUARE$MAIN\7,LINE 9 
I 9: DO 10 I = 1. N 

IFORSQUARE$MAIN\N: 3 

IFORSQUARE$MAIN\K: 0 

I stepped to FORSQUARE$MAIN\'/,LINE 11 
IFORSQUARE$MAIN\I: 1 

IFORSQUARE$MAIN\K: 0 

I 

I 

I - PROMPT -error-program-prompt- 

|DBG> STEP 

IDG> EXAMINE I.K 

|DBG> 
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8.2.5 The Predefined Register Display REG 

The predefined register display REG automatically shows the current values 
of all VAX machine registers (see the example that follows). REG also shows 
the four condition code bits (C,V, Z, and N) of the processor status longword 
(PSL), plus the top several values on the stack and on the current argument 
list. The values in this display are highlighted when they change as you 
execute the program. 

REG is initially marked as removed (see Section 8.3.2) from the display 
pasteboard and is not visible. You need to use the DISPLAY command (or 
the keypad key sequence GOLD-7) to show the REG display. 


- SRC: module FORSQUAREfMAIN -scroll-sou-*-- REG -.. 

RIO:7FFEDDD4 
Rll:000004A0 
AP :7FF4A1CC 
FP :7FF4A180 
SP :7FF4A180 
PC :0000064D 
(DAP: 00000006 
+4:7FFE6440 
-*■8: 7FF9F4EB 
+12:7FFE640C 
V:0 C:0 

I - OUT -output-+- 

I stepped to FORSQUARE$MAIN\'/,LINE 4 
I stepped to FORSQUARE$MAIN\'/,LINE 5 
I stepped to F0RSQUARE$MAIN\7.LINE 8 
IFORSQUAREIMAINXI: 5 

IFORSQUARE$MAIN\K: 0 

IF0RSQUARE$MAIN\N: 4 

I 

I - PROMPT -error-program-prompt- 

|DBG> STEP 

|DBG> EXAMINE I,K,N 

|DBG> 

| -- 


I 


3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 


C -Read the input array IRO:00000000 

OPEN(UNIT=8, FILE=’DATAFIR1:00000008 
READ(8,*) N, (INARR(I), |R2:00000000 
C |R3:7FF4A194 

C -Square all non-zero eIR4:00000000 

K = 0 IR5:00000000 

DO 10 I = 1. N |R6:7FF49E49 

IF(INARR(I) .NE. 0) THEN IR7:8001E4DD 
K = K + 1 IR8:7FFED052 

OUTARR(K) = INARIR9:7FFED25A 
END IF | N:0 Z:0 


.I 

(DSP: 000000001 
+4:080000001 
+8:7FF4A1CCI 
+12:7FF4A1B8I 
+16:000196C8| 
+20:7FFE33DCI 
+24:000009FFI 
+28:000000051 
+32:000006001 
+36:000000001 
+40:000000011 

.I 

I 


I 

I 

I 

I 


I 

I 

I 


8.3 Manipulating Existing Displays 

This section explains how to 

• Use the SELECT and SCROLL commands to scroll a display 
(Section 8.3.1). 

• Use the DISPLAY command to show, hide, or remove a display; the 
CANCEL DISPLAY command to permanently delete a display; and the 
SHOW DISPLAY command to identify the displays that currently exist 
and their order in the display list (Section 8.3.2). 

• Use the MOVE command to move a display across the screen 
(Section 8.3.3). 

• Use the EXPAND command to expand or contract a display 
(Section 8.3.4). 
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8.3.1 Scrolling a Display 

A display usually has more lines of text (and possibly longer lines) than can 
be seen through its window. The SCROLL command lets you view text that 
is hidden beyond a window's border. You can scroll through all displays 
except for the PROMPT display. 

The easiest way to scroll displays is with keypad keys, as described later in 
this section. First, use of the relevant commands will be explained. 

You can specify a display explicitly with the SCROLL command. Typically, 
however, you first use the SELECT/SCROLL command to select the current 
scrolling display. This display then has the scroll attribute and is the default 
display for the SCROLL command. You can then use the SCROLL command 
with no parameter to scroll that display up or down by a specified number of 
lines, or to the right or left by a specified number of columns. The direction 
and distance scrolled are specified with the command qualifiers (/UP:n, 
/RIGHT:n, and so on). 

In the following example, the SELECT command selects display OUT as the 
current scrolling display (/SCROLL may be omitted because it is the default 
qualifier); the SCROLL command then scrolls OUT to reveal text 18 lines 
down: 

dbg> select out 

DBG> SCROLL/DOWN:18 

Several useful SELECT and SCROLL command lines are assigned to keypad 
keys (see Appendix B for the keypad diagram): 

• Pressing key 3 assigns the scroll attribute to the next display in the 
display list after the current scrolling dipslay. So, to select a display as 
the current scrolling display, press key 3 repeatedly until the word "scroll" 
appears on the top line of that display. 

• Press key 8, 2, 6, or 4 to scroll up, down, right, or left, respectively. The 
amount of scroll depends on which key state you use (DEFAULT, GOLD, 
or BLUE). 


8.3.2 Showing, Hiding, Removing, and Canceling a Display 

The DISPLAY command is the most versatile command for manipulating 
existing displays. The basic syntax is: 

DISPLAY display-name [AT window-specification] [display-kind] 

The display name must be that of an existing display. The other parameters 
let you change the window specification and the display kind (see Sections 8.5 
and 8.6 for information on how to specify windows and display kinds). 

When used without a qualifier or any parameters, the DISPLAY command 
simply puts a display on top of the pasteboard where it appears through its 
current window. For example, the following command shows the display 
INST through its current window: 

DBG> DISPLAY INST 

Keypad key 9, which is bound to the command DISPLAY %NEXTDISP, 
lets you achieve this effect for each display in the display list. The built- 
in function %NEXTDISP signifies the next display in the list (Appendix D 
identifies all screen-related built-in functions). Each time you press key 9, the 
next display is put on top of the pasteboard, in its current window. Note that. 
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by default, the top line of display OUT (which identifies the display) coincides 
with the bottom line of display SRC. If SRC is on top of the pasteboard, its 
bottom line will hide the top line of OUT (keep this in mind when using the 
DISPLAY command and associated keypad keys to put various displays on 
top of the pasteboard). 

To hide a display at the bottom of the pasteboard, use the DISPLAY/HIDE 
command. This command simply changes the order of that display in the 
display list. 

To remove a display from the pasteboard so that it is no longer seen (yet is 
not permanently deleted), use the DISPLAY/REMOVE command. To put a 
removed display back on the pasteboard, use the DISPLAY command. 

To delete a display permanently, use the CANCEL DISPLAY command. To 
recreate the display, use the SET DISPLAY command, which is described in 
Section 8.4. 

Note that you cannot hide, remove, or delete the PROMPT display. 

To identify the displays that currently exist, use the SHOW DISPLAY 
command. They are listed according to their order on the display list. The 
display that is on top of the pasteboard is listed last. 

See the Command Dictionary for information on the various options provided 
by the DISPLAY command qualifiers. 


8.3.3 Moving a Display Across the Screen 

The MOVE command lets you move a display across the screen. The 
qualifiers /UP:n, /DOWN:n, /RIGHT:n, and /LEFT.n specify the direction 
and the number of lines or columns by which to move the display. If you do 
not specify a display, the current scrolling display is moved. 

The easiest way to move a display is by using keypad keys: 

• Press key 3 repeatedly as needed to select the current scrolling display. 

• Put the keypad in the MOVE state, then use keys 8, 2, 4, or 6 to move 
the display up, down, left, or right, respectively (see Appendix B). 


8.3.4 Expanding or Contracting a Display 

The EXPAND command lets you expand or contract a display. The qualifiers 
/UP:n, /DOWN:n, /RIGHT:n, and /LEFT:n specify the direction and the 
number of lines or columns by which to expand or contract the display (to 
contract a display, specify negative integer values with these qualifiers). If 
you do not specify a display, the current scrolling display is expanded or 
contracted. 

The easiest way to expand or contract a display is by using keypad keys. 

• Press key 3 repeatedly as needed to select the current scrolling display. 

• Put the keypad in the EXPAND or CONTRACT state, then use keys 8, 

2, 4, or 6 to expand or contract the display vertically or horizontally (see 
Appendix B). 

Note that the PROMPT display cannot be contracted (or expanded) 
horizontally. Also, it cannot be contracted vertically to less than two lines. 
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8.4 Creating a New Display 

To create a new screen display, use the SET DISPLAY command. The basic 
syntax is: 

SET DISPLAY display-name [AT window-specification] [display-kind] 

The display name can be any name that is not already used to name a 
display. When you create a new display, it is placed on top of the pasteboard, 
on top of any existing displays (except for the predefined PROMPT display, 
which cannot be hidden). The display name appears at the top left comer of 
the display window. 

Section 8.5 explains the options you have for specifying windows. If you do 
not provide a window specification, the display is positioned in the upper or 
lower half of the screen, alternating between these locations as you create 
new displays. 

Section 8.6 explains the options you have for specifying display kinds. If you 
do not specify a display kind, an output display is created. 

For example, the following command creates a new output display named 
OUT2. The window associated with OUT2 is either the top or bottom half of 
the screen. 

DBG> SET DISPLAY 0UT2 

The following command creates a new "DO" display named EXAM_XY that 
is located in the right third quarter (RQ3) of the screen. This display shows 
the current value of variables X and Y and is updated whenever the debugger 
gains control from the program. 

DBG> set DISPLAY EXAM.XY AT RQ3 DO (EXAMINE X.Y) 

See the Command Dictionary for information on the various options provided 
by the SET DISPLAY command qualifiers. 


8.5 Specifying a Display Window 

Display windows may occupy any rectangular portion of the screen. 

You can specify a display window when creating a display with the SET 
DISPLAY command. You can also change the window currently associated 
with a display by specifying a new window with the DISPLAY command. 
You have the following options: 

• Specify a window in terms of lines and columns. 

• Use the name of a predefined window, such as HI. 

• Use the name of a window definition previously established with the SET 
WINDOW command. 

Each of these techniques is described in the next sections. When specifying 
windows, keep in mind that the PROMPT display always remains on top 
of the display pasteboard and, therefore, will occlude any part of another 
display that shares the same region of the screen. 

Display windows, regardless of how specified, are dynamic. This means that, 
if you use a SET TERMINAL command to change the screen height or width, 
the window associated with a display will expand or contract in proportion to 
the new screen height or width. 
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8.5.1 Specifying a Window in Terms of Lines and Columns 

The general form of a window specification is (start-line ,line-count[ f start- 
column,column-count]). For example, the following command creates the 
output display CALLS and specifies that its window be 7 lines deep starting 
at line 10, and 30 columns wide starting at column 50: 

DBG> SET DISPLAY CALLS AT (10,7,50,30) 

If you do not specify start-column or column-count , the window occupies the 
full width of the screen. 


8.5.2 The Predefined Windows 

The debugger provides many predefined windows. These have short 
symbolic names that you can use in the SET DISPLAY and DISPLAY 
commands instead of having to specify lines and columns. For example, 
the following command creates the output display ZIP and specifies that its 
window be RH1 (the top right half of the screen). 

DBG> SET DISPLAY ZIP AT RH1 

The predefined windows are all identified in Appendix C. The SHOW 
WINDOW command also displays these definitions. 


8.5.3 Creating a New Window Definition 

Although the predefined windows should be adequate for most situations, 
you can create a new window definition with the SET WINDOW command. 
This command, which has the following form, associates a window name 
with a window specification: 

SET WINDOW window-name AT (start-line,line-count[,start-col,col-count]) 

After creating a window definition, you can simply use its name (like that 
of a predefined window) in a SET DISPLAY or DISPLAY command. In the 
following example, the window definition MIDDLE is established. That 
definition is then used to display OUT through the window MIDDLE. 

DBG> SET WINDOW MIDDLE AT (9,4,30,20) 

dbg> display out at middle 

To identify all current window definitions, use the SHOW WINDOW 
command. To delete a window definition, use the CANCEL WINDOW 
command. 


8.6 Specifying the Display Kind 

Every display has a display kind. The display kind determines the type of 
information a display contains and how that information is generated. 

Typically, you specify a display kind when using the SET DISPLAY command 
to create a new display (if you do not specify a display kind, an output 
display is created). You can also specify a display kind when using the 
DISPLAY command to change a display kind. The keywords and associated 
parameters with which you specify a display kind are listed below. Each of 
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these options is explained in the sections that follow (refer also to the displays 
illustrated in Section 8.2). 

DO (command-list) 

INSTRUCTION 
INSTRUCTION (command) 

OUTPUT 

REGISTER 

SOURCE 

SOURCE (command) 


The contents of a register display are generated and updated automatically 
by the debugger. The contents of other kinds of displays are generated by 
commands, and these display kinds fall into two general groups. 


A display that belongs to one of the following display kinds has its contents 
updated automatically according to the command or command list you supply 
when defining that display. 


DO (command-list) 
INSTRUCTION (command) 
SOURCE (command) 


The command list specified is executed each time the debugger gains control 
from your program, provided the display is not marked as removed. The 
output of the commands forms the new contents of the display. If the display 
is marked as removed, the debugger does not execute the command list until 
you view that display (marking that display as unremoved). 


A display that belongs to one of the following display kinds derives its 
contents from commands that you issue interactively: 


INSTRUCTION 

OUTPUT 

SOURCE 


To direct debugger output to a specific display in this group, you must first 
select it with the SELECT command. The technique is explained in the next 
sections and, in further detail, in Section 8.7. Once a display is selected for a 
certain type of output, the output from your commands forms the contents of 
the display. 


The default size of the memory buffer associated with any newly created 
display is 64 lines. For source and instruction displays, the size of the buffer 
only affects performance. In the case of a source display, source files will 
be paged in as necessary as you scroll through the module. In the case of 
an instruction display, the instructions will be decoded from the image as 
necessary as you scroll through the routine. 


For output and DO displays, the buffer size defines how many lines of text 
the display will hold. If you add more text to the display, the oldest lines are 
discarded to make room for the new text. You can use the /SIZE qualifier on 
the SET DISPLAY and DISPLAY commands to change the buffer size. 
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8.6.1 DO (command-list) Display Kind 

A "DO" display is an automatically updated display. The commands in the 
command list are executed each time the debugger gains control from your 
program. Their output forms the content of the display, erasing any previous 
content. 

For example, the following command creates the DO display CALLS at 
window Q3. Each time the debugger gains control from the program, the 
SHOW CALLS command is executed and the output is displayed in CALLS, 
replacing any previous contents. 

DBG> SET DISPLAY CALLS AT Q3 DO (SHOW CALLS) 


8.6.2 INSTRUCTION Display Kind 

An instruction display shows the output of an EXAMINE/INSTRUCTION 
command within the assembly-language instruction code of the routine being 
debugged (the instructions displayed are decoded from the image being 
debugged). One line is devoted to each instruction. Source line numbers 
corresponding to the instructions are displayed in the left column. The 
instruction at the location being examined is centered in the display and is 
marked by an arrow in the left column. 

Note that, before anything can be written to an instruction display, you must 
select it as the current instruction display with the SELECT/INSTRUCTION 
command. 

In the following example, the SET DISPLAY command creates the 
instruction display INST2 at RH1. The SELECT/INSTRUCTION 
command then selects INST2 as the current instruction display. When 
the EXAMINE/INSTRUCTION X command is executed, window RH1 fills 
with the instruction code surrounding the location X. The arrow points to the 
instruction at location X, which is centered in the display. 

DBG> SET DISPLAY INST2 AT RH1 INSTRUCTION 
DBG> SELECT/INSTRUCTION INST2 

dbg> examine/instruction X 

Each subsequent EXAMINE/INSTRUCTION command will update the 
display. 


8.6.3 INSTRUCTION (command) Display Kind 

This is an instruction display that is automatically updated with the 
output of the command specified. That command, which must be an 
EXAMINE/INSTRUCTION command, is executed each time the debugger 
gains control from your program. 

For example, the following command creates the instruction display INST3 
at window RS45. Each time the debugger gains control, the command 
EXAMINE/INSTRUCTION .0\%PC is executed (it displays the instruction at 
the current PC location), updating the display. 

DBG> SET DISPLAY INST3 AT RS45 INSTRUCTION (EX/INST .0\y.PC) 

This command creates a display that functions like the predefined display 
INST. 
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If an automatically updated instruction display is selected as the current 
instruction display, it will be updated like a simple instruction display by 
an interactive EXAMINE/INSTRUCTION command (in addition to being 
updated by its built-in command). 


8.6.4 OUTPUT Display Kind 

An output display shows any debugger output that is not directed to some 
other display. New output is appended to the previous contents of the 
display. 

Note that, before anything can be written to an output display, it must be 
selected as the current output display with the SELECT/OUTPUT command, 
or as the current error display with the SELECT/ERROR command, or as the 
current input display with the SELECT/INPUT command. See Section 8.7 for 
more information on using the SELECT command with output displays. 

In the following example, the SET DISPLAY command creates the output 
display OUT2 at window T2 (the display kind OUTPUT could have been 
omitted from this example, since it is the default kind). The SELECT 
/OUTPUT command then selects OUT2 as the current output display. These 
two commands create a display that functions like the predefined display 
OUT. 

DBG> set DISPLAY 0UT2 AT T2 OUTPUT 
DBG> SELECT/OUTPUT 0UT2 

OUT2 will now collect any debugger output that is not directed to another 
display. For example: 

• The output of a SHOW CALLS command will go to OUT2. 

• If no instruction display has been selected as the current instruction 
display, the output of an EXAMINE/INSTRUCTION command will go to 
OUT2. 

• By default, debugger diagnostic messages are directed to the PROMPT 
display. They may be directed to OUT2 with the SELECT/ERROR 
command. 


8.6.5 REGISTER Display Kind 

A register display is an automatically updated display that shows the current 
contents of all VAX machine registers, the four condition code bits (C, V, Z, 
and N) of the processor status longword (PSL), and the top several values 
on the stack and on the current argument list. The display is updated each 
time the debugger gains control from your program. Any values that have 
changed are highlighted. 

As opposed to other display kinds, a register display is not dynamic by 
default. It does not change its window dimensions in proportion if you 
change the terminal screen height or width. 
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8.6.6 SOURCE Display Kind 

A source display shows the output of a TYPE or EXAMINE/SOURCE 
command within the source code of the module being debugged, if that 
source code is available. Source line numbers are displayed in the left 
column. The source line that is the output of the command is centered in the 
display and is marked by an arrow in the left column. If a range of lines is 
specified with the TYPE command, the lines are centered in the display, but 
no arrow is shown. 

Note that, before anything can be written to a source display, you must select 
it as the current source display with the SELECT/SOURCE command. 

In the following example, the SET DISPLAY command creates the source 
display SRC2 at Q2. The SELECT/SOURCE command then selects SRC2 as 
the current source display. When the TYPE 34 command is executed, window 
RH1 fills with the source code surrounding line 34 of the module being 
debugged. The arrow points to line 34, which is centered in the display. 

DBG> SET DISPLAY SRC2 AT Q2 SOURCE 
DBG> SELECT/SOURCE SRC2 
DBG> TYPE 34 

Each subsequent TYPE or EXAMINE/SOURCE command will update the 
display. 


8.6.7 SOURCE (command) Display Kind 

This is a source display that is automatically updated with the output of the 
command specified. That command, which must be an EXAMINE/SOURCE 
or TYPE command, is executed each time the debugger gains control from 
your program. 

For example, the following command creates a source display SRC3 at 
window RS45. Each time the debugger gains control, the command 
EXAMINE/SOURCE .%SOURCE_SCOPE\%PC is executed, updating the 
display. 

DBG> SET DISPLAY SRC3 AT RS45 SOURCE (EX/SOURCE . # /.S0URCE_SC0PE\7.PC) 

This command creates a display that functions like the predefined display 
SRC. %SOURCE_SCOPE is a built-in scope that signifies scope 0 when 
source lines are available for scope 0. Otherwise, it signifies scope N, where 
N is the first level down the call stack for which source lines are available. 

If an automatically updated source display is selected as the current source 
display, it will be updated like a simple source display by an interactive 
EXAMINE/SOURCE or TYPE command (in addition to being updated by its 
built-in command). 


8.6.8 PROGRAM Display Kind 

The PROMPT display belongs to the special display kind "program." Note 
that PROMPT is the only display of that kind. You cannot specify that 
display kind in a SET DISPLAY or DISPLAY command. 

To avoid possible confusion, the PROMPT display has several restrictions (see 
Section 8.2.3). 
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8.7 Assigning Display Attributes 

In screen mode, the output from commands you issue interactively is directed 
to various displays according to the type of output and the attributes assigned 
to these displays. For example, debugger diagnostic messages go to the 
display that has the error attribute (the current error display). By assigning 
one or more attributes to a display, you can mix or isolate different kinds of 
information. 

The attributes have the following names: error, input, instruction, output, 
program, prompt, scroll, and source. When a display is assigned an attribute, 
the name of that attribute appears in lowercase letters on the top border of its 
window, to the right of the display name. Note that the scroll attribute does 
not affect debugger output but is used to control the default display for the 
SCROLL, MOVE, and EXPAND commands. 

By default, attributes are assigned to the predefined displays as follows: 

• For all languages except MACRO, SRC has the source and scroll 
attributes. 

• For MACRO, INST has the instruction and scroll attributes. 

• OUT has the output attribute. 

• PROMPT has the prompt, program, and error attributes. 

To assign an attribute to a display, use the SELECT command with the 
qualifier of the same name as the attribute. In the following example, the SET 
DISPLAY command creates the output display ZIP. The SELECT/OUTPUT 
command then selects ZIP as the current output display —the display that has 
the output attribute. After this command is executed, the word "output" will 
disappear from the top border of the predefined output display OUT and will 
appear instead on display ZIP, and all debugger output formerly directed to 
OUT will now be directed to ZIP. 

DBG> SET DISPLAY ZIP OUTPUT 
DBG> SELECT/OUTPUT ZIP 

Specific attributes may be assigned only to certain display kinds. The 
following list identifies each of the SELECT command qualifiers, its effect, 
and the display kinds to which you can assign that attribute. 


SELECT 

Qualifier Description 

/ERROR Selects the specified display as the current error display. 

Directs any subsequent debugger diagnostic message to that 
display. It must be either an output display or the PROMPT 
display. If no display is specified, selects the PROMPT 
display as the current error display. 

/INPUT Selects the specified display as the current input display. 

Echoes any subsequent debugger input in that display. 

It must be an output display. If no display is specified, 
unselects the current input display: debugger input is not 
echoed to any display. 
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SELECT 

Qualifier 

Description 

/INSTRUCTION 

Selects the specified display as the current instruction 
display. Directs the output of any subsequent EXAMINE 
/INSTRUCTION command to that display. It must be an 
instruction display. Keypad key sequence BLUE-COMMA 
selects the next instruction display in the display list as 
the current instruction display. If no display is specified, 
unselects the current instruction display: no display has the 
instruction attribute. 

/OUTPUT 

Selects the specified display as the current output display. 
Directs any subsequent debugger output to that display, 
except where a particular type of output is being directed 
to another display (such as diagnostic messages going to 
the current error display). The specified display must be 
either an output display or the PROMPT display. Keypad 
key sequence GOLD-3 selects the next output display in the 
display list as the current output display. If no display is 
specified, selects the PROMPT display as the current output 
display. 

/PROGRAM 

Selects the specified display as the current program display. 
Tries to force any subsequent program input or output to 
that display. Currently, only the PROMPT display may be 
specified. If no display is specified, unselects the current 
program display: program output is no longer forced to the 
PROMPT display. 

/PROMPT 

Selects the specified display as the current prompt display, 
where the debugger prompts for input. Currently, only the 
PROMPT display may be specified. You cannot unselect the 
PROMPT display. 

/SCROLL 

Selects the specified display as the current scrolling display. 
Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify 
any display (however, note that the PROMPT display cannot 
be scrolled). /SCROLL is the default if you do not specify a 
qualifier with the SELECT command. Key 3 selects as the 
current scrolling display the next display in the display list 
after the current scrolling display. If no display is specified, 
unselects the current scrolling display: no display has the 
scroll attribute. 

/SOURCE 

Selects the specified display as the current source display. 
Directs the output of any subsequent TYPE or EXAMINE 
/SOURCE command to that display. It must be a source 
display. Keypad key sequence BLUE-3 selects the next 
source display in the display list as the current source 
display. If no display is specified, unselects the current 
source display: no display has the source attribute. 


Subject to the restrictions listed, a display can have several attributes. In the 
preceding example, ZIP was selected as the current output display. In the 
next example, ZIP is further selected as the current input, error, and scrolling 
display. After these commands are executed, debugger input, output, and 
diagnostics will be logged in ZIP in the proper sequence as they occur, and 
ZIP will be the current scrolling display. 

dbg> select/input/error/scroll zip 
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To identify the displays currently selected for each of the display attributes, 
use the SHOW SELECT command. 

If you use the SELECT command with a particular qualifier but without 
specifying a display name, the effect is typically to de-assign that attribute (to 
"unselect" the display that had the attribute). The exact effect depends on the 
attribute, as described in the preceding list. 


8.8 A Sample Display Configuration 

How to best use screen mode depends on your personal style and on what 
type of bug you are looking for. You may be satisfied to simply use the 
predefined displays. On the other hand, especially if you have access to 
a larger screen, you may want to create additional displays for various 
purposes. The following example may give you some ideas. 

Assume you are debugging in a high-level language and are interested in 
tracing the execution of your program through several routine calls. 

First set up the default screen configuration—that is, SRC in HI, OUT in 
S45, and PROMPT in S6 (the keypad key sequence BLUE-MINUS gives this 
configuration). SRC will show the source code of the currently executing 
module. 

The next command creates a source display named SRC2 in RH1 that shows 
the PC location at scope 1 (one level down the call stack, at the call to the 
currently executing module): 

DBG> set DISPLAY SRC2 AT RH1 SOURCE (EXAMINE/SOURCE . 1V/.PC) 

Thus the left half of your screen shows the currently executing routine, 
whereas the right half shows the caller of that routine. 

The next command creates a DO display named CALLS at S4 that executes 
the SHOW CALLS command each time the debugger gains control from the 
program: 

DBG> set DISPLAY CALLS AT S4 DO (SHOW CALLS) 

Since the top half of OUT is now hidden by CALLS, make OUT's window 
smaller: 

dbg> display OUT AT S5 

You can create a similar display configuration with instruction displays 
instead of source displays. 


8.9 Saving Displays and the Screen State 

The SAVE command lets you make a "snapshot" of an existing display and 
save that copy as a new display. This is useful if, for example, you later want 
to refer to the current contents of an automatically updated display (such as a 
DO display). 

In the following example, the SAVE command saves the current contents of 
display CALLS into display CALLS4, which is created by the command: 

DBG> SAVE CALLS AS CALLS4 
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The new display is removed from the pasteboard. So, to view its contents use 
the DISPLAY command: 

DBG> DISPLAY CALLS4 

The EXTRACT command has two uses. First, it lets you save the contents 
of a display in a text file. For example, the following command extracts 
the contents of display CALLS, appending the resulting text to the file 
COB34.TXT: 

DBG> EXTRACT/APPEND CALLS C0B34 

Second, the EXTRACT/SCREEN—LAYOUT command lets you create a 
command procedure that may later be invoked during a debugging session 
to re-create the previous state of the screen. In the following example, the 
EXTRACT/SCREEN— LAYOUT command creates a command procedure with 
the default specification SYS$DISK:[]DBGSCREEN.COM. The file contains all 
the commands needed to recreate the current state of the screen. 

DBG> EXTRACT/SCREEN.LAYOUT 


DBG> ODBGSCREEN 

Note that you cannot save the PROMPT display as another display, or extract 
it into a file. 


8.10 Changing the Screen Height and Width 

During a debugging session, you may want to change the height or width 
of your terminal screen. One reason may be to accommodate long lines that 
would wrap if displayed across 80 columns. Or, if you are using a Micro VAX 
workstation, you may want to reformat your debugger window relative to 
other windows. 

To change the screen height or width, use the SET TERMINAL command. 
The general effect of the command is the same whether you are at a VT-series 
terminal or at a Micro VAX workstation. 

In this example, assume you are using a workstation in its default emulated 
VTlOO-screen mode, with a screen size of 24 lines by 80 columns. You have 
invoked the debugger and are using it in screen mode. You now want to 
take advantage of the larger screen. The following command increases the 
screen height and width of the debugger window to 35 lines and 110 columns 
respectively: 

DBG> SET TERMINAL/PAGE:35/WIDTH:110 

By default, all displays except for register displays are "dynamic/ A dynamic 
display automatically adjusts its window dimensions in proportion when 
a SET TERMINAL command changes the screen height or width. This 
means that, when using the SET TERMINAL command, you preserve the 
relative positions of your displays. The /[NOJDYNAMIC qualifier on the 
DISPLAY and SET DISPLAY commands lets you control whether or not a 
display, including a register display, is dynamic. If a display is not dynamic, 
it does not change its window coordinates after you issue a SET TERMINAL 
command (you can then use the DISPLAY, MOVE, or EXPAND commands, 
or various keypad key combinations, to move or resize a display). 

To see the current terminal width and height being used by the debugger, use 
the SHOW TERMINAL command. 
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Note that the debugger's SET TERMINAL command does not affect the 
terminal screen size at DCL level. When you exit the debugger, the original 
screen size is maintained. 
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9 Tailoring the Debugger 


The debugger has certain specialized features that allow you to tailor your 
debugging sessions to the design of your particular program as well as your 
own individual needs. These features allow you to 

• Allocate additional memory 

• Use control structures 

• Declare parameters to command procedures 

• Define and undefine commands 

• Define and undefine keys 


9.1 Allocating Additional Memory 

The debugger has an internal memory pool from which it provides both 
temporary and permanent memory. The data structures the debugger builds 
when it processes a command need only temporary memory. Since these data 
structures are discarded as soon as the command is processed, the memory 
they occupy can be reused for other processing. On the other hand, data 
structures (such as breakpoints) which remain during the debugging session 
need permanent memory. 

Most of the memory pool is used to store the run-time symbol table (RST) for 
the modules that you have set with the SET MODULE command. Typically, 
the debugger memory pool allows you to set your six largest modules. 

However, your program may have many large modules that you want to set 
all at the same time, and the normal memory allocation may not be adequate 
to include all these symbols in the RST. To solve this problem, you can 
allocate additional memory with either the ALLOCATE or the SET 
MODULE/ALLOC ATE command. 


9.1.1 The ALLOCATE Command 

The ALLOCATE command gives you explicit control over the size of the 
debugger memory pool. It allows you to increase the virtual address 
space allotted to the debugger. This is the space that the debugger uses 
to store symbol table and eventpoint information, for instance. You can use 
this command if you get the "NOFREE" error message indicating that the 
debugger has run out of free virtual memory. The command has the form 

ALLOCATE byte-count 

The byte-count parameter specifies the number of bytes you want to add 
to the debugger memory pool. You must request at least 1000 bytes. You 
can find out the size of the memory pool by giving the command SHOW 
MODULE. The size is shown in the "remaining size:" line. This number 
represents the number of free bytes that are still in the pool. 
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The SHOW MODULE command also tells how many bytes are needed to 
set each module in your program. You can use these size requirements as a 
guideline for deciding how many bytes to allocate. 

You should allocate extra memory only at the beginning of your debugging 
session. You can, however, allocate additional memory in the middle of 
a debugging session, but memory allocation within your program may be 
affected if your program calls LIB$GET_VM. Since the debugger also uses 
LIB$GET_VM (to increase the size of memory pool), the memory your 
program allocates may be interleaved with that allocated by the debugger. 
This is usually not a problem, but in some cases, the behavior of your 
program may be affected. 

For more information, see the ALLOCATE command in the Command 
Dictionary. 


9.1.2 The SET MODULE/ALLOCATE Command 

The /ALLOCATE qualifier on SET MODULE tells the debugger to allocate 
extra storage if necessary in order to complete the SET MODULE command. 

Normally the debugger tries to allocate all its storage at the beginning of the 
debugging session, before your program has run. So, any SET MODULE 
command that is issued before you execute a STEP or GO command will 
allocate storage if necessary, whether or not you specify /ALLOCATE. 

After your program has run, the debugger will not allocate memory because 
the debugger memory may be interleaved with your program's memory and 
this may affect the behavior of the program. Therefore, after your program 
has run, if you need extra memory allocation during a SET MODULE, you 
must explicitly ask for it by using SET MODULE/ALLOC ATE. 

The following example shows how to use the ALLOCATE command, the SET 
MODULE/ALLOCATE and the SHOW MODULE command. 
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Example 9-36 Using the ALLOCATE, the SET MODULE/ALLOCATE, the SET 



MODULE/ALL, 

and the SHOW MODULE Commands 

DBOSHOW MODULE 

{Display 

module names and sizes. 

module name 

symbols 

language 

size 

DISTANCE$MAIN 

yes 

FORTRAN 

15600 

DIST 

no 

FORTRAN 

5420 

SUB1 

no 

FORTRAN 

10000 

SUB 2 

no 

FORTRAN 

5260 

SHARElFORRTL 

no 

Image 

0 

SHARE$LIBRTL 

no 

Image 

0 

SHARE$MTHRTL 

no 

Image 

0 

SHAREIDEBUG 

no 

Image 

0 

SHARElLBRSHR 

no 

Image 

0 

SHARE$PLIRTL 

no 

Image 

0 

SHARE$SCRSHR 

no 

Image 

0 

SHARE$SMGSHR 

no 

Image 

0 

total modules: 12. 

remaining size: 46260. 

DBG>SET MODULE/ALL 

!Set all modules at the beginning 
!of the debugging session. 

DBOSHOW MODULE 

{Display all set modules. Note that 
!no shareable image is set. 

module name 

symbols 

language 

size 

DISTANCElMAIN 

yes 

FORTRAN 

15600 

DIST 

yes 

FORTRAN 

5420 

SUB1 

yes 

FORTRAN 

10000 

SUB 2 

yes 

FORTRAN 

5260 

SHARE$FORRTL 

no 

Image 

0 

SHARElLIBRTL 

no 

Image 

0 

SHARElMTHRTL 

no 

Image 

0 

SHAREIDEBUG 

no 

Image 

0 

SHAREILBRSHR 

no 

Image 

0 

SHAREIPLIRTL 

no 

Image 

0 

SHAREISCRSHR 

no 

Image 

0 

SHAREISMGSHR 

no 

Image 

0 

total modules: 12. 

remaining size: 20000. 


(Continued on next page) 


9-3 









Tailoring the Debugger 


9.2 


Example 9-36 (Cont.) Using the ALLOCATE, the SET MODULE/ALLOCATE, the SET 

MODULE/ALL, and the SHOW MODULE Commands 


DBG> SET MODULE/ALLOCATE SHARE$FORRTL 

!Explicitly request that the 
!shareable image be set, regardless 
!of size. 

DBG>SHOW MODULE IDisplay set modules. Note that 

!SHARE$FORRTL is now set. 


module name 

symbols 

language 

size 

DISTANCEIMAIN 

yes 

FORTRAN 

15600 

DIST 

yes 

FORTRAN 

5420 

SUB1 

yes 

FORTRAN 

10000 

SUB2 

yes 

FORTRAN 

5260 

SHAREIFORRTL 

yes 

Image 

11600 

SHARElLIBRTL 

no 

Image 

0 

SHAREIMTHRTL 

no 

Image 

0 

SHAREIDEBUG 

no 

Image 

0 

SHAREILBRSHR 

no 

Image 

0 

SHAREIPLIRTL 

no 

Image 

0 

SHAREISCRSHR 

no 

Image 

0 

SHARElSMGSHR 

no 

Image 

0 


total modules: 10. remaining size: 8400. 

DBG>SET MODULE SHARElLIBRTL !Try to set smother module. 
y,DEBUG-E-NOFREE , no tree storage available 


DBG>ALLOCATE 15000 !Explicitly expand the memory pool 

!by 15000 bytes. Alternately, you 
!could have used the command 
!SET MODULE/ALLOCATE. 


DBG>SET MODULE SHARElLIBRTL !Try to set the module again. 
DBG> SHOW MODULE IDisplay all modules. 


module name 

symbols 

language 

size 

DISTANCEIMAIN 

yes 

FORTRAN 

15600 

DIST 

yes 

FORTRAN 

5420 

SUB1 

yes 

FORTRAN 

10000 

SUB2 

yes 

FORTRAN 

5260 

SHAREIFORRTL 

yes 

Image 

11600 

SHARElLIBRTL 

yes 

Image 

19652 

SHAREIMTHRTL 

no 

Image 

0 

SHAREIDEBUG 

no 

Image 

0 

SHAREILBRSHR 

no 

Image 

0 

SHAREIPLIRTL 

no 

Image 

0 

SHAREISCRSHR 

no 

Image 

0 

SHAREISMGSHR 

no 

Image 

0 

total modules: 12. 

remaining 

size: 4200. 


For more information. 
Dictionary. 

see the SET MODULE command in the Command 


Using Control Structures 


The debugger's command language is a specialized programming language 
that consists primarily of primitive operations, or simple commands, such as 
EXAMINE and SET BREAK. However, as in other programming languages, 
the effectiveness and flexibility of these simple commands are enhanced by 
conditional or looping constructs. The debugger presently includes three such 
control structures: the FOR, IF, REPEAT, and WHILE commands. 
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9.2.1 The FOR Command 

The FOR command allows a debugger command list to be executed iteratively 
for a specified number of times. It has the form 

FOR name = expressionl TO expression2 [BY expressions] DO (command-list) 

The behavior of the FOR command depends on the values of the expression3 
parameter. If expression3 is positive, name is incremented from the value of 
expressionl by the value of expression3 until it is greater than the value of 
expression2. 

If expression3 is negative, name is decremented from the value of expressionl 
by the value of expression3 until it is less than the value of expression2. 

If expression3 is zero, the debugger returns an error message. 

If expression3 is left out entirely, the debugger assumes it to have the value 

+ 1 . 

Example 9-37 shows how to use the FOR command (FORTRAN example). 


Example 9-37 Using the FOR command 


DBG>FOR COUNT s 1 TO 4 DO (STEP) !Set up a loop that 

DBG>stepped to DISTANCE$MAIN\'/,LINE 5 ! steps to the next 

5: STATUS=LIB$GET_LUN(L0G_UNIT) Ifour lines, 

stepped to DISTANCE$MAIN\7.LINE 6 

6: OPEN (UNIT=LOG_UNIT,FILE=’FOR.DAT *,STATUS= * OLD *) 

stepped to DISTANCE$MAIN\7.LINE 7 

7: DO WHILE (XI .NE. -9.9) 

stepped to DISTANCE$MAIN\7.LINE 8 

8: READ (UNIT=LOG_UNIT.FMT=100) X1.X2.Y1.Y2 


DBG> SHOW SYMBOL COUNT !Display symbol COUNT 

defined COUNT 


DBG> EVALUATE COUNT !Display current value 

4 !of COUNT 

DBG> REPEAT 4 DO (STEP) !Another way of iterating 

stepped to DISTANCE$MAIN\7.LINE 10 !a debugger command 

10: D = DIST(X1,X2,Y1,Y2) 

stepped to DISTANCE$MAIN\7.LINE 16 
16: TYPE 200,XI 

stepped to DI STAN CE$MA IN \ '/.LI NE 17 
17: TYPE 201,X2 

stepped to DISTANCE$MAIN\7.LINE 18 
18: TYPE 202,Y1 


For more information, see the FOR command in the Command Dictionary. 
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9.2.2 The IF Command 

The IF command allows a debugger command list to be executed 
conditionally if a language expression is evaluated as TRUE. It has the 
form 

IF boolean-expression THEN (command-list) [ELSE (command-list)] 

The IF command evaluates a language-specific boolean-expression. If the 
value is TRUE (as defined in the current language), the debugger command 
list in the THEN clause is executed. If the expression is FALSE, the command 
list in the ELSE clause is executed (if it is present). 

Example 9-38 shows how to use the IF command (FORTRAN example). 

Example 9-38 Using the IF Command 


DBG>IF XI .NE. -9.9 THEN (EXAMINE X2) ELSE (EX Yl) 
DISTANCE$MAIN\X2: 0.OOOOOOO 

!Examine the variable 
!X2 if XI is not equal 
1-9.9; otherwise, 
{examine the variable 
! Yl. 


DBG>F0R 

stepped 

19: 

stepped 

20 : 

stepped 

21 : 

stepped 

7: 


COUNT = 1 TO 4 DO (IF XI .NE. -9.9 THEN (STEP)) 


to DISTANCE$MAIN\%LINE 19 
TYPE 203,Y2 

to DISTANCE$MAIN\%LINE 20 
TYPE 204,D 

to DISTANCE$MAINV/,LINE 21 
END DO 

to DISTANCE$MAINV/.LINE 7 


!Set up a control 
{structure to step 
{four lines as long 
!as XI does not equal 
! -9 . 9 


DO WHILE (XI .NE. -9.9) 


For more information, see the IF command in the Command Dictionary. 


9.2.3 The WHILE Command 

The WHILE command allows the debugger command lists to be executed 
iteratively until the language expression you have specified evaluates as 
FALSE. It has the form 

WHILE boolean-expression DO (command-list) 

If the value is TRUE (as defined in the current language), the debugger 
command list in the DO clause is executed. The command then repeats 
the sequence specified by the DO command-list, reevaluating the boolean- 
expression and executing the command-list until the expression is evaluated 
as FALSE. 

If the boolean-expression is FALSE, the WHILE command terminates. 
Example 9-39 shows how to use the WHILE command (FORTRAN example). 
For more information, see the WHILE command in the Command Dictionary. 
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Example 9-39 Using the WHILE Command 


DBG>WHILE X2 .LE. XI DO (EX X2;STEP) 

DISTANCE$MAIN\X2: 5.500000 

stepped to DISTANCE$MAIN\%LINE 8 

8: READ (UNIT=LOG_UNIT,FMT=100) X1,X2,Y1,Y2 


DISTANCE$MAIN\X2: 5.500000 

stepped to DISTANCE$MAIN\%LINE 10 

10: D = DIST(X1,X2,Y1,Y2) 

DISTANCE$MAIN\X2: 5.000000 

stepped to DISTANCE$MAIN\%LINE 16 
16: TYPE 200,XI 

DISTANCE$MAIN\X2: 5.000000 

stepped to DISTANCE$MAIN\%LINE 17 
17: TYPE 201,X2 

DISTANCE$MAIN\X2: 5.000000 


!Examine the variable 
!X2 and then step 
!to the next line 
!while it is less 
!than the variable 
!X1. 


9.3 Declaring Parameters to Command Procedures 

Another special feature of the debugger, the DECLARE command, allows you 
to pass parameters to command procedures. You can use this command only 
in a debugger command procedure. 

Each parameter declaration has the same effect as a DEFINE command: it 
binds a name (the formal parameter) to a value or other construct (the actual 
parameter). 

The format of the DECLARE command is 

DECLARE fname:pkind [.fnarne:pkind [,...]] 

The fnarne parameter specifies the formal parameter name. The pkind 
parameter may take the types below. 

ADDRESS Causes the actual parameter to be interpreted as an address 
expression. It has the same effect as the command DEFINE 
/ADDRESS fnarne = actual-parameter. 

VALUE Causes the actual parameter to be interpreted as a language 

expression. It has the same effect as the command DEFINE 
/VALUE fnarne = actual-parameter. 

COMMAND Causes the actual parameter to be interpreted as a command 

string. It has the same effect as the command DEFINE/COMMAND 
fnarne = actual-parameter. 

You can specify more than one fname:pkind pair with a single DECLARE 
command. Each fname:pkind pair acts like a separate DECLARE command, 
and each pair binds one parameter. So, for instance, if you want to pass 
five parameters to a command procedure, you need five corresponding 
fnarne:pkind pairs in the command procedure itself. The pairs are always 
processed in the order in which you specify them. 

The %PARCNT symbol specifies the number of actual parameters to the 
current command procedure. For example, suppose the command file ABC 
is invoked with the command @ABC 111,222,333. Inside ABC, %PARCNT 
then has the value 3 because there are three parameters on this particular call 
to ABC. %PARCNT is used in command procedures that can take a variable 
number of actual parameters. %PARCNT can only be used inside command 
files; it is not defined when commands are entered from the terminal. 
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A sample format follows: 

EVALUATE y,PARCNT 

FOR I * 1 TO 7.PARCNT DO (DECLARE X:VALUE; EVALUATE X) 

The following example shows a command procedure containing a DECLARE 
command and how it is used during a debugging session. 

Example 9-40 Using the DECLARE Command in a Command 
Procedure 


DBG>SET OUTPUT VERIFY 


{Turn on VERIFY so the 
•command in the command 
{procedure will echo. 


DBGX8EXAM OPTIONS {Execute the procedure. 

%DEBUG-I-VERIFYICF, entering indirect command file "EXAM.COM" 


DECLARE PI:ADDRESS 
EXAMINE PI 

C0NV_EX$MAIN\0PTI0NS 


( 1 ) 

( 2 ) 

(3) 

(4) 

(5) 

( 6 ) 

(7) 

( 8 ) 

(9) 

( 10 ) 
( 11 ) 
( 12 ) 

(13) 

(14) 

(15) 

(16) 

(17) 

(18) 
(19) 


18 

1 

0 

1 

0 

0 

1 

2 

0 

0 

0 

0 

0 

0 

0 

0 

0 

1 

0 


{OPTIONS is passed to 
!the procedure as PI. 
{Examine OPTIONS. 


7.DEBUG-1 - VERIFYICF, exiting indirect command file "EXAM.COM" 


9.4 Defining and Undefining Commands 

The debugger has yet another special feature that allows you to define your 
own commands. With the DEFINE/COMMAND command, you can assign 
character strings to symbolic names. When the symbolic name appears at 
the start of a subsequent debugger command, the name is replaced by the 
string it represents. As a result, the symbolic name acts like a new debugger 
command. 

To define complex commands, you may need to use indirect command 
files with parameters (for example, DEFINE/COMMAND DUMP = 
"@DUMP.COM"). For more information on declaring parameters to 
command files, see the Section 9.9.3. 

The DEFINE/COMMAND command provides essentially the same 
capabilities as the DCL command "symboli^arameter." 

Example 9-41 shows how to define your own debugger commands. 
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Example 9-41 Defining Debugger Commands 


"EXAMINE '/.NEXTLOC" 

!Define the command EXN. 
!Display that it has 
!been defined. 


DBG> DEFINE/COMMAND EXN = 

DBG> SHOW SYM/DEFINED EXN 
defined EXN 

bound to: "EXAMINE ‘/.NEXTLOC" 
was defined /command 

DBG> EX XI 

DISTANCE$MAIN\X1: 0.OOOOOOO 

DBG> EXN 

DISTANCE$MAIN\X2: 0.OOOOOOO 

DBG> EXN 

DISTANCE$MAIN\Y1: 0.OOOOOOO 


!Examine a location. 

!Use the defined symbol EXN 
!to examine the next 
!locations. 


9.5 Defining and Undefining Keys 

The debugger allows you to modify the functions of the keypad keys to suit 
your individual needs. With the DEFINE/KEY, SHOW KEY, and DELETE 
/KEY (or UNDEFINE/KEY) commands, you can set, show, and delete key 
definitions, respectively. Before you can use this feature, keypad mode must 
be enabled with the SET MODE KEYPAD command (keypad mode is enabled 
by default). Keypad mode also lets you use the predefined functions of the 
keypad keys. 

However, most of the keypad functions are associated with screen mode 
commands. If you want to use all the predefined functions of the keypad 
keys, you must first set the mode to screen mode with the SET MODE 
SCREEN command. 


9.5.1 Assigning Key Definitions 

The DEFINE/KEY command allows you to assign your own definitions to the 
numeric keypad keys. When you press the appropriate keypad key, the string 
associated with that key is inserted into the command line. You can also 
use qualifiers with the DEFINE/KEY command to associate certain attributes 
with the performance of the key. You must set mode to keypad to use this 
command. 

The DEFINE/KEY command has the form 

DEFINE/KEY key-name "equiv-string" 

The key-name parameter specifies the name of the key that you are defining. 
In addition, for single words without special symbols, you do not need to 
enclose the equivalence string in quotation marks. 

The standard definable key names are listed below. 


Key-name LK201 VT100-type VT52-type 


PF1 

PF1 

PF1 

Blue 

PF2 

PF2 

PF2 

Red 

PF3 

PF3 

PF3 

Black 

PF4 

PF4 

PF4 
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Key-name 


LK201 

VT100-type 

VT52-type 

KPO, KP1, . 

. . ,KP9 

Keypad 0, ... ,9 

Keypad 0, ... ,9 

Keypad 0, ... ,9 

PERIOD 


Keypad period (.) 

Keypad period (.) 


COMMA 


Keypad comma (,) 

Keypad comma (,) 


MINUS 


Keypad minus (-) 

Keypad minus (-) 


ENTER 


ENTER 

ENTER 

ENTER 

El 


Find 



E2 


Insert Here 



E3 


Remove 



E4 


Select 



E5 


Prev Screen 



E6 


Next Screen 



HELP 


Help 



DO 


Do 



F6, F7 

, F20 

F6, F7.F20 




The ability to define keys can save both time and keystrokes. If, for instance, 
you use a particular debugger command (or set of commands) repetitively, 
you can define one of the keypad keys as that command. Then when you 
press the defined key, the key definition is treated as a debugger command. 

The DEFINE/KEY command provides the same capabilities as the DCL 
command DEFINE/KEY. 

For additional information on defining keys, refer to the DEFINE/KEY 
command in the Command Dictionary as well as in the VAX/VMS DCL 
Dictionary. 

Example 9-42 shows how to define the keypad keys with debugger 
commands. 

Example 9-42 Using the DEFINE/KEY Command 


DBG>SET MODE KEYPAD !Set the mode the keypad. 

DBG>DEFINE/KEY PF1 "SET STEP/INSTRUCTION" 

y,DEBUG- 1-DEFKEY, DEFAULT key PF1 has been defined 

!Define the PF1 key. 

!The definition is 
!echoed because /LOG 
!i8 the default. 

DBG>DEF INE/KEY/TERMINATE PF3 "SET OUTPUT LOG" 

yj)EBUG- I-DEFKEY, DEFAULT key PF3 has been defined 

!Define the PF3 key. 

!When you press this 
!key, the command will 
!execute automatically 
'.because of the 
!/TERMINATE qualifier. 
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Tailoring the Debugger 


9.5.2 Using Debugger-Defined Key Definitions 

The debugger provides a number of predefined command definitions for 
the numeric keypad keys. Although most of these definitions apply only to 
screen mode functions, you can still use some of the keypad definitions while 
you are using the regular line-oriented debugger. 

These keys and their functions are identified in Appendix B. 


9.5.3 Showing Key Definitions 

You can see the key definitions you have created with the SHOW KEY 
command. 

The command has the form 

SHOW KEY [key-name] 

The key-name parameter specifies the name of the key whose definition 
you want to see. This command provides the same capabilities of the DCL 
command SHOW KEY. 

If you want to see all key definitions, use the command SHOW KEY/ALL. 

Example 9-43 shows how to show the definitions associated with each 
keypad key. 

Example 9-43 Using the SHOW KEY Command 


DBG> SHOW KEY PF1 

DEFAULT keypad definitions: 

PF2 = "SET STEP/INSTRUCTION" (echo.noterminate,nolock) 

!Display the command you 
lhave associated with 
!the PF1 key. 

DBG> SHOW KEY PF3 

DEFAULT keypad definitions: 

PF3 ■ "SET OUTPUT LOG" (echo.terminate.nolock) 

!Display the command you 
lhave associated with 
Ithe PF3 key. 


DBG> SHOW KEY KP3 


DEFAULT keypad definitions: 

KP3 = "Select/Source '/.Nextsource" (noecho. terminate .nolock) 

!Display the default 
'.debugger command associated 
Iwith the PF3 key. 


For additional information on displaying key definitions, refer to the SHOW 
KEY command in the Command Dictionary as well as in the VAX/VMS DCL 
Dictionary. 
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Tailoring the Debugger 


9.5.4 Deleting Key Definitions 

To delete key definitions you have established with the DEFINE/KEY 
command, use either the DELETE/KEY or the UNDEFINE/KEY command. 

They have the forms 

DELETE/KEY [key-name] 

UNDEFINE/KEY [key-name] 

The key-name parameter specifies the name of the key whose definition you 
want to delete. 

Both commands provide the same capabilities of the DCL command DELETE 
/KEY. 

Example 9-44 shows how to use, how to delete or undefine the numeric 
keypad keys. 

Example 9-44 Using the DELETE/KEY and UNDEFINE/KEY 
Commands 


DBOSET MODE KEYPAD ! Set mode to keypad. 

DBG>DELETE/KEY PF1 !Delete the PF1 key. 

‘/.DEBUG -1- DELKEY, DEFAULT key PF1 has been deleted 

DBG>UNDEFINE/KEY/NOLOG PF3 

!Undefine the PF3 key. 
!The debugger does not 
!display a message that 
!the key has been 
{undefined because of 
!the /LOG qualifier. 


For more information on deleting key definition, see either the DELETE/KEY 
or the UNDEFINE/KEY commands in the Command Dictionary. 


9-12 











Part II Debugger Command Dictionary 












The Debugger Command Dictionary describes each of the debugger 
commands in detail. The following information is provided for each 
command: 

• Command description 

• Command format 

• Command parameters 

• Command qualifiers 

• One or more examples 

Refer to the Preface for documentation conventions. 


CD.1 Debugger Command Format 

A command string is the complete specification of a debugger command. 
Although you can continue a command on more than one line, the term 
command string is used to define an entire command that is passed to the 
debugger. 

A debugger command string consists of a verb and, possibly, parameters and 
qualifiers. 

The verb specifies the command to be executed. Some debugger command 
strings may consist of only a verb or a verb pair. For example: 

DBG> GO 

DBG> SHOW IMAGE 

A parameter specifies what the verb acts on (for example, a file specification). 
A qualifier describes or modifies the action taken by the verb. Some 
command strings may include one or more parameters or qualifiers. In 
the following examples, COUNT, I, J, and K, and PROG4 are parameters; 
/SCROLL and /OUTPUT are qualifiers. 

DBG> SET WATCH COUNT 

DBG> EXAMINE I.J.K 

DBG> SELECT/SCROLL/OUTPUT PR0G4 

Some commands accept optional WHEN or DO clauses. A WHEN clause 
consists of the keyword WHEN followed by a conditional expression (within 
parentheses) that evaluates to TRUE or FALSE in the current language. A 
DO clause consists of the keyword DO followed by one or more command 
strings (within parentheses) that are to be executed. Multiple command 
strings should be separated by semicolons (;). These points are illustrated in 
the next example. 

The following command string sets a breakpoint on routine SWAP that will 
be triggered whenever the value of J equals 4 during execution. When the 
breakpoint is triggered, the debugger executes the two command strings 
SHOW CALLS and EXAMINE I,K, in the order indicated. 

DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I.K) 

DO clauses are also used in some screen display definitions. 
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CD.2 Entering and Terminating Commands 


You can enter debugger commands interactively at the terminal or store 
them within a command procedure to be invoked later with the @file-spec 
command. The conventions are described for each mode of operation. 


CD.2.1 At the Terminal 


When entering a command interactively, you can abbreviate a keyword (verb, 
qualifier, parameter) to as few characters as are needed to make it unique 
within the set of all keywords. However, some commonly used commands 
(for example, EXAMINE, DEPOSIT, GO, STEP) can be abbreviated to their 
first characters. Also, in some cases, the debugger interprets nonunique 
abbreviations correctly on the basis of context. 

Pressing the RETURN key terminates the current line, causing the debugger 
to process it. To continue a long command string on another line, type a 
hyphen (-) before pressing RETURN. The debugger prompt will be prefixed 
with an underline character (_DBG> ), indicating that the command string is 
still being accepted. 

You can enter more than one command string on one line by separating them 
with a semicolon (;). 

The command line editing functions that are available at the DCL prompt 
are also available at the debugger prompt, including command recall with 
the up-arrow and down-arrow keys. For example, pressing the left-arrow 
and right-arrow keys moves the cursor one character to the left and right, 
respectively; pressing CTRL/H and CTRL/E moves the cursor to the start and 
end of the line respectively; pressing CTRL/U deletes all the characters to the 
left of the cursor, and so on. 

To interrupt a command that is in progress, press CTRL/Y. This will put you 
at DCL level. You can then type either CONTINUE or DEBUG to return to 
the debugging session. (See the description of CTRL/Y in the Command 
Dictionary.) 


CD.2.2 In a Command Procedure 

To maximize legibility, it is best to not abbreviate command keywords in a 
command procedure. In any case, as with DCL commands, do not abbreviate 
command keywords to less than four significant characters (not counting the 
negation /NO . . . ), to avoid potential conflicts in future releases. 

In a command procedure, the start of a new line terminates the previous line. 
To continue a command string on another line, type a hyphen (-) before 
starting the new line. 

You can enter more than one command string on one line by separating them 
with a semicolon (;). 

A comment is a string that is preceded by an exclamation point (!). 
Comments do not affect the execution of debugger commands. 
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ALLOCATE 


ALLOCATE 

Expands the debugger memory pool. 

FORMAT 

ALLOCATE byte-count 

PARAMETERS byte-count 

Specifies the number of bytes by which you want to expand the debugger 
memory pool. The byte-count must be at least 1000; if it is not, you will 
receive an error message. You will also receive an error message if the system 
is unable to allocate the memory you requested. 

QUALIFIERS 

None. 

DESCRIPTION 

Module setting, the process by which symbol records are loaded into the 
debugger's run-time symbol table, requires memory to be allocated. By 
default, dynamic module setting is enabled and the debugger automatically 
allocates memory as it sets modules. If you issue the SET MODE 
NODYNAMIC command to disable dynamic module setting, you will have to 
set modules yourself. In that case, memory is not allocated automatically, and 
you may need to use the ALLOCATE command in order to set more modules. 
The SHOW MODULE command tells you how much space is required to set 
each module as well as how much space is available. 

When you use the ALLOCATE command, the debugger calls $EXPREG 
to provide the extra memory. If your program also allocates memory 
dynamically, the location of the allocated memory in your program may 
be affected. 

Related commands: (SET, CANCEL, SHOW) MODULE, SET MODE 
[NO]DYNAMIC. 

EXAMPLE 



DBG> ALLOCATE 20000 


This command increases the size of the memory pool by an additional 20000 
bytes. 
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^file-spec 


@file-spec 

Executes debugger commands contained in the specified command 
procedure. 

FORMAT 

@file-spec[PI [,P2, . . . ,Pn]] 

PARAMETERS file-spec 

Specifies the command procedure to be executed. For any part of the full 
file specification that is not provided, the debugger uses the file specification 
established with the last SET ATSIGN command, if any. If the missing part 
of the file specification was not established by a SET ATSIGN command, the 
debugger assumes SYS$DISK:[ JDEBUG.COM as the default file specification. 

p 

Specifies a parameter that is declared inside the command procedure. Note 
that, unlike with DCL, parameters must be separated by commas. For 
more information on declaring parameters to command procedures, see the 
DECLARE command description. 

QUALIFIERS 

None. 

DESCRIPTION 

A command procedure can contain any debugger commands, including 
another @file-spec command. The debugger executes commands from the 
command procedure until it reaches an EXIT or QUIT command or the end 
of the file. At that point, the debugger returns control to the command 
stream that invoked the command procedure. A command stream can be the 
terminal, an outer (containing) command procedure, a DO clause in a SET 
BREAK, SET TRACE, or SET WATCH command, or a DO clause in a screen 
display definition. 

If you enter SET OUTPUT VERIFY, all commands read from a command 
procedure are echoed on the current output device, as specified by 
DBG$OUTPUT (the default output device is SYS$OUTPUT, the terminal). 

Related commands: (SET, SHOW) ATSIGN. 


CD-4 












^file-spec 


EXAMPLE 


DBG> SET ATSIGN USER:[JONES.DEBUG].DBG 
DBG> SET OUTPUT VERIFY 
DBG> <BMAIN 

%DEBUG-I-VERIFYICF, entering indirect command file "MAIN" 
SET MODULE/ALL 
SET BREAK SUB1 
GO 

breads at routine MAIN\SUB1 
EXAMINE/WORD SUB1 
SUB1\SUB1: 4800 

EXAMINE/INST 

SUBl\SUBl+02: MOVAL L~SUB1\Y,R11 
EXIT 

7.DEBUG-I-VERIFYICF, exiting indirect command file "MAIN" 
DBG> 


The SET ATSIGN command establishes that debugger command procedures 
reside, by default, in USER:[JONES.DEBUG] and have a file type of DBG. The 
SET OUTPUT VERIFY command causes all commands to echo at the terminal 
before they execute. The @MAIN command causes the command procedure 
USER:[JONES.DEBUG]MAIN.DBG to be executed. 
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ATTACH 


ATTACH 

Passes control of your terminal from the current process to another 
process. 

FORMAT 

ATTACH process-name 

PARAMETERS process-name 

Specifies the process to which your terminal is to be attached. The process 
must already exist before you try to attach to it. If the process name contains 
non-alphanumeric characters or spaces, you must enclose it in quotation 
marks (""). 

QUALIFIERS 

None. 

DESCRIPTION 

The ATTACH command allows you to go back and forth between a 
debugging session and your command interpreter, or between two debugging 
sessions. To do so, you must first spawn a subprocess (see the description 
of the SPAWN command); you can then attach to it whenever you want. To 
return to your original process with minimal system overhead, use another 
ATTACH command. 

Related commands: SPAWN. 


EXAMPLES 


Q DBG> SPAWN 

$ ATTACH JONES 

'/.DEBUG-1-RETURNED, control returned to process JONES 
DBG> ATTACH JONES. 1 

$ 

This series of commands spawns a subprocess named JONES—l from the 
debugger (currently running in the process JONES) and then attaches to that 
subprocess. 

Q DBG> ATTACH "Alpha One" 

$ 


This example illustrates use of quotation marks to enclose a process name 
that contains a space. 
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CALL 


CALL 

Calls a routine that was linked with your program 


FORMAT CALL routine-name [(argument[, ...])] 


PARAMETERS routine-name 

Specifies the name or the virtual address of the routine to be called. 

argument 

Specifies an argument that is required by the routine. Arguments can be 
passed by address (the default), by descriptor, by reference, and by value, as 
described below. 


%ADDR 

Passes the argument by address. This is the default. The format is 
the following: 

CALL routine-name C/.ADDR address-expression) 

%DESCR 

The debugger evaluates the address expression and passes that 
address to the routine specified. For simple variables (such as X), the 
address of X is passed into the routine. This passing mechanism 
is how FORTRAN implements ROUTINE(X). In other words, for 
named variables, using %ADDR corresponds to a call by reference 
in FORTRAN. For other expressions, however, you must use the %REF 
function to call by reference. 

Passes the argument by descriptor. The format is the following: 

CALL routine-name (%DESCR language-expression) 

%REF 

The debugger evaluates the language expression and builds a VAX- 
standard descriptor to describe the value. The descriptor is then 
passed to the routine you named. You would use this technique to 
pass strings to a FORTRAN routine. 

Passes the argument by reference. The format is the following: 

CALL routine-name (%REF language-expression) 

%VAL 

The debugger evaluates the language expression and passes a 
pointer to the value, into the called routine. This passing mechanism 
corresponds to the way FORTRAN passes the result of an expression. 

Passes the argument by value. The format is the following: 

CALL routine-name C/.VAL language-expression) 

The debugger evaluates the language expression and passes the value 
directly to the called routine. 
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CALL 


QUALIFIERS /[NOJAST 

Controls whether aynchronous system traps (ASTs) are enabled or disabled 
during the execution of the called routine. /AST specifies that ASTs be 
enabled (can be delivered). /NOAST specifies that ASTs be disabled (cannot 
be delivered). If you do not specify /AST or /NOAST, ASTs will be enabled 
in the called routine if, and only if, they were currently enabled at the time of 
the call. 


DESCRIPTION The CALL command is one of four debugger commands that execute code 

(the others are GO, STEP, and EXIT). You can use the CALL command to 
call a routine and debug it independently of the rest of the program. You 
can also use the command to call user-written routines that dump debugging 
information. 

The CALL command executes a routine whether or not your program actually 
includes a call to that routine, so long as the routine was linked with your 
program. You can debug unrelated routines by linking them with a dummy 
main program that has a transfer address, and then using the CALL command 
to execute them. 

When you issue a CALL command, the debugger takes the following action: 

1 Saves the current values of the general registers 

2 Constructs an argument list 

3 Executes a call to the routine specified in the command and passes any 
arguments 

4 Executes the routine 

5 Displays the value returned by the routine in RO 

6 Restores the values of the general registers to the values they had just 
before the CALL command was executed 

7 Issues the DBG> prompt 

The debugger assumes that the called routine conforms to the VAX/VMS 
procedure calling standard (see the VAX Architecture Handbook). However, 
note that the debugger does not know about all the argument-passing 
mechanisms for all supported languages. You therefore may need to specify 
how to pass parameters—for example, use CALL SUB1(%VAL X) rather 
than CALL SUB1(X). Also, routines may not be called correctly if you are 
using complicated arguments such as arrays or records. See your language 
documentation for complete information on how arguments are passed to 
routines. 


EXAMPLES 

Q DBG> CALL SUBl(X) 

value returned is 19 


This command calls the routine SUB1, passing "X" as the required parameter. 
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CALL 


0 DBG> CALL SUB (‘/.REF 1) 

value returned is 1 


This command passes a pointer to a memory location containing the numeric 
literal 1, into the routine SUB. 
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CANCEL ALL 


CANCEL ALL 



Cancels all breakpoints, tracepoints, and watchpoints. Restores any 
modes established with the SET MODE command to their default 
values. Restores the scope and type to their default values. 

FORMAT 

CANCEL ALL 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The CANCEL ALL command does the following: 

• Cancels all eventpoints (breakpoints, tracepoints, watchpoints). This 
is equivalent to issuing the CANCEL BREAK, CANCEL TRACE, and 
CANCEL WATCH commands. 

• Restores the scope search list to its default value (0,1,2, . . . ,n). This is 
equivalent to issuing the CANCEL SCOPE command. 

• Restores the data type associated with a typed memory location to the 
compiler generated type. Restores the type associated with untyped 
memory locations to "longword integer". This is equivalent to issuing the 
CANCEL TYPE/OVERRIDE and SET TYPE LONGWORD commands. 

• Restores the modes established with the SET MODE command to their 
default values. This is equivalent to issuing the following command: 

DBG> SET MODE KEYPAD,NOSCREEN,DYNAMIC,LINE,SYMBOLIC,N0G_FL0AT,SCROLL 

The CANCEL ALL command does not affect the current language setting or 

modules included in the run-time symbol table (SET MODULE). 

Related commands: CANCEL BREAK, CANCEL TRACE, CANCEL WATCH, 

CANCEL SCOPE, CANCEL TYPE/OVERRIDE, (SET, CANCEL) MODE. 

EXAMPLE 


DBG> CANCEL ALL 

This command cancels all the eventpoints you have set previously. It also 
restores scope, modes and types to their default values. 
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CANCEL BREAK 


CANCEL BREAK 

Cancels breakpoints. 


FORMAT CANCEL BREAK [address-expressionf, . . . ]] 


PARAMETERS address-expression 

Specifies a breakpoint to be canceled. Do not use the wildcard character (*). 
Do not specify an address expression when using any of the qualifiers except 
for /EVENT. 


QUALIFIERS /ALL 

Cancels all breakpoints. Do not use the wildcard character (*). When using 
/ALL, do not specify an address expression. 

/BRANCH 

Cancels the effect of a previous SET BREAK/BRANCH command. Do not 
specify an address expression with /BRANCH. 

/CALL 

Cancels the effect of a previous SET BREAK/CALL command. Do not specify 
an address expression with /CALL. 

/EVENT=event-name 


Note: /EVENT applies only to Ada and SCAN. See the VAX Ada and VAX 
SCAN documentation for complete information. 

Cancels the effect of a previous SET BREAK/EVENT=event-name command. 
The effect of CANCEL BREAK/EVENT=event-name is symmetrical with the 
effect of SET BREAK/EVENT=event-name. To cancel a breakpoint, specify 
the event name and address expression (if any) exactly as you did with the 
SET BREAK/EVENT command, excluding any WHEN or DO clauses. Event 
names depend on the run-time facility and are identified in Appendix E for 
Ada and SCAN. You can also display the event names associated with the 
current run-time facility by issuing the SHOW EVENT-FACILITY command. 

/EXCEPTION 

Cancels the effect of a previous SET BREAK/EXCEPTION command. Do not 
specify an address expression with /EXCEPTION. 

/INSTRUCTION 

Cancels the effect of a previous SET BREAK/INSTRUCTION command. Do 
not specify an address expression with /INSTRUCTION. 
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CANCEL BREAK 



/LINE 

Cancels the effect of a previous SET BREAK/LINE command. Do not specify 
an address expression with /LINE. 

DESCRIPTION 

The effect of the CANCEL BREAK command is symmetrical with the effect of 
the SET BREAK command. 

To cancel a breakpoint that was established at a specific location with 
the SET BREAK command, specify that same location with the CANCEL 
BREAK command. To cancel breakpoints that were established on a class 
of instructions or events by using a qualifier with the SET BREAK command 
(/CALL, /LINE, /EXCEPTION, /EVENT, and so on), specify that same 
qualifier with the CANCEL BREAK command. 

Generally, you must specify either an address expression or a qualifier, 
but not both. The only exception is with the /EVENT qualifier, which 
requires that you specify an event name and lets you also specify an address 
expression for certain event names. 

Note that the command CANCEL ALL also cancels all breakpoints. 

Related commands: (SET, SHOW) BREAK, (SET, CANCEL) EXCEPTION 
BREAK, (SET, SHOW, CANCEL) TRACE, CANCEL ALL. 


EXAMPLES 

Q DBG> CANCEL BREAK MAIN\L00P+10 

This command cancels the breakpoint set at the address expression 
M AIN\LOOP+l 0. 

Q DBG> CANCEL BREAK/ALL 

This command cancels all breakpoints you have set previously. 
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CANCEL DISPLAY 


CANCEL DISPLAY 



Permanently deletes a screen display. 

FORMAT 

CANCEL DISPLAY [disp-name[, ... 77 


PARAMETERS disp-name 

Specifies the name of a display to be canceled. Do not specify the PROMPT 
display, which cannot be canceled. Do not use the wildcard character (*). 
When using /ALL, do not specify a display name. 


QUALIFIERS /ALL 

Cancels all displays, except for the PROMPT display. When using /ALL, do 



not specify a display name. 

DESCRIPTION 

When a display is canceled, its contents are permanently lost, it is removed 
from the display list, and all the memory that was allocated to it is released. 

You cannot cancel the PROMPT display. 

Related commands: (SET, SHOW) DISPLAY, (SET, SHOW, CANCEL) 
WINDOW. 


EXAMPLE 


DBG> CANCEL DISPLAY SRC2 

This command permanently deletes display SRC2. 

DBG> CANCEL DISPLAY/ALL 

This command permanently deletes all displays, except for the PROMPT 
display. 
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CANCEL EXCEPTION BREAK 


CANCEL EXCEPTION BREAK 

Cancels exception breakpoints. 

FORMAT 

CANCEL EXCEPTION BREAK 

PARAMETERS 

None. 

QUALIFIERS 

None. 

DESCRIPTION 

The command CANCEL EXCEPTION BREAK cancels the effect of the 
command SET EXCEPTION BREAK. As a result of the cancellation, exception 
conditions generated by your program are handled in the following way: 

• The debugger fields and resignals the exception. 

• Any exception handlers you have defined in your program are executed. 

• If you have not defined an exception handler or if an exception handler 
that you have defined resignals the exception, a diagnostic message is 
issued and control is returned to the debugger, which then displays its 
prompt. 

Related commands: SET EXCEPTION BREAK, (SET, CANCEL) BREAK 
/EXCEPTION, CANCEL ALL. 

EXAMPLE 



DBG> CANCEL EXCEPTION BREAK 


This command cancels the effect of a previous SET EXCEPTION BREAK 
command. 
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CANCEL IMAGE 


CANCEL IMAGE 

Removes run-time symbol table information for a shareable image. 

FORMAT 

CANCEL IMAGE [ image-name [, ... 77 

PARAMETERS 

image-name 

Specifies a previously set shareable image that is to be canceled. Do not 
specify the main image, which cannot be canceled. Do not use the wildcard 
character (*). When using /ALL, do not specify an image name. 

QUALIFIERS 

/ALL 

Specifies that all shareable images except the main image are to be canceled. 
When using /ALL, do not specify an image name. 

DESCRIPTION 

The CANCEL IMAGE command deallocates the data structures previously 
built to debug a shareable image by a SET IMAGE command. The CANCEL 
IMAGE command can be used when the run-time symbol table is full and 
debugger performance is slowed down. 

If the current image (the image last set with the SET IMAGE command) is 
canceled, the main image becomes the current image. 

Related commands: (SET, SHOW) IMAGE, (SET, SHOW, CANCEL) 
MODULE. 

EXAMPLES 



Q DBG> CANCEL IMAGE SHARE2, SHARE3 

The CANCEL IMAGE command cancels shareable images SHARE2 and 
SHARE3. If either of these was the current image, the main image becomes 
the current image. 
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CANCEL MODE 


CANCEL MODE 



Restores all modes controlled by the SET MODE command to their 
default values. Also restores the default input/output radix. 

FORMAT 

CANCEL MODE 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The effect of the CANCEL MODE command is equivalent to issuing the 
following commands: 

DBG> SET MODE KEYPAD.NOSCREEN,DYNAMIC,LINE,SYMBOLIC,NOG.FLOAT,SCROLL 

DBG> CANCEL RADIX 

Note that, although the same default modes apply to all languages, the 
default radix is hexadecimal for BLISS and MACRO and decimal for all other 
languages. 

Related commands: (SET, SHOW) MODE, (SET, SHOW, CANCEL) RADIX. 


EXAMPLE 


DBG> CANCEL MODE 

This command restores the default radix mode and all default mode values. 
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CANCEL MODULE 


CANCEL MODULE 


Deletes the symbol records of a module from the run-time symbol 
table (RST). 


FORMAT CANCEL MODULE [modnamef, . . . ]] 


PARAMETERS modname 

Specifies the name of a module whose symbol records are to be deleted from 
the RST. Do not use the wildcard character (*). When using /ALL, do not 
specify a module name. 


QUALIFIERS /ALL 

Deletes the symbol records of all modules from the RST. When using /ALL, 
do not specify a module name. 

/[NOJRELATED 

Note: /[NOJRELATED applies only to Ada programs. 

Controls whether the debugger deletes from the RST the symbol records of a 
module that is related to a specified module through a with-clause or subunit 
relationship. 

CANCEL MODULE/RELATED (default) deletes symbol records for related 
modules as well as for those specified, but not for any module that is also 
related to another set module. The effect of CANCEL MODULE/RELATED 
is consistent with Ada's scope and visibility rules and depends on the actual 
relationship between modules. CANCEL MODULE/NORELATED deletes 
symbol records only for modules that are specified (no symbol records are 
deleted for related modules). 


DESCRIPTION 

Note: The (SET, SHOW, CANCEL) MODULE commands operate on modules in 
the current image. This is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 

The CANCEL MODULE command is useful under two general conditions: 

• If dynamic module setting is enabled (this is the default condition) and 
performance becomes a problem as the debugger sets more and more 
modules dynamically. 

• If dynamic module setting is disabled and you cannot use the SET 
MODULE command (because the RST is full), but do not want to use the 
ALLOCATE command to increase the debugger memory pool. 


Related commands: (SET, SHOW) MODULE, SET MODE [NOJDYNAMIC, 
ALLOCATE, (SET, SHOW, CANCEL) IMAGE. 
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CANCEL MODULE 


EXAMPLES 

Q DBG> CANCEL MODULE SUB1 

This command removes the symbols of module SUB1 from the run-time 
symbol table. 

Q DBG> CANCEL MODULE/ALL 

This command removes the symbols of all modules from the run-time symbol 
table (RST). 
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CANCEL RADIX 


CANCEL RADIX 



Restores the default radix for the entry and display of integers. 

FORMAT 

CANCEL RADIX 


PARAMETERS None. 


QUALIFIERS 

/OVERRIDE 

Cancels the override radix established by a previous SET RADIX/OVERRIDE 
command. This sets the current override radix to "none" and restores the 
output radix mode to the value established with a previous SET RADIX or 
SET RADIX/OUTPUT command. If you did not change the radix mode 
with a SET RADIX or SET RADIX/OUTPUT command, the CANCEL 
RADIX/OVERRIDE command restores the radix mode to its default value 
(hexadecimal for BLISS and MACRO, decimal for other languages). 

DESCRIPTION 

The CANCEL RADIX command cancels the effect of any previous SET 
RADIX and SET RADIX/OVERRIDE commands. It restores the input and 
output radix to their default value (hexadecimal for BLISS and MACRO, 
decimal for other languages). 

The effect of the CANCEL RADIX/OVERRIDE command is more limited and 
is explained in the description of the /OVERRIDE qualifier. 

Related commands: (SET, SHOW) RADIX. 


EXAMPLE 

dbg> cancel radix 

This command restores the default input and output radix. 

dbg> cancel radix/override 

This command cancels any override radix you may have set with the SET 
RADIX/OVERRIDE command. 
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CANCEL SCOPE 


CANCEL SCOPE 



Restores the default scope for symbol lookup. 

FORMAT 

CANCELSCOPE 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The CANCEL SCOPE command cancels the current scope search list 
established by a previous SET SCOPE command and restores the default 
scope search list, namely 0,1,2, ... ,N, where N is the number of calls in the 
call stack. 

The default scope means that, for a symbol without a path-name prefix, a 
symbol lookup such as "EXAMINE X" first looks for X in the routine that is 
currently executing (scope 0); if no X is visible there, the debugger looks in 
the caller of that routine (scope 1), and so on down the call stack; if X is not 
found in scope N, the debugger searches the rest of the run-time symbol table 
(RST), then searches the global symbol table (GST), if necessary. 

Related commands: (SET, SHOW) SCOPE. 

EXAMPLE 


DBG> CANCEL SCOPE 

This command cancels the current scope. 
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CANCEL SOURCE 


CANCEL SOURCE 



Cancels a source directory search list established by a previous SET 
SOURCE command. 

FORMAT 

CANCELSOURCE 


PARAMETERS None. 


QUALIFIERS /EDIT 

Note: /EDIT applies mainly to Ada programs. 



Cancels the effect of a previous SET SOURCE/EDIT command. As a result, 
when you use the EDIT command, the debugger searches for a source file in 
the same directory that it was in at compile time. The CANCEL SOURCE 
/EDIT command does not cancel the effect of a previous SET SOURCE 
command. 

/MODULE=module-name 

Cancels the effect of a previous SET SOURCE/MODULE=module-name 
command in which the same module name was specified. ( module-name 
specifies a module for which a source directory search list is to be canceled). 
As a result, the debugger searches for the source file of the specified module 
in the same directory that it was in at compile time. The CANCEL SOURCE 
/MODULE=module-name command does not cancel the effect of a previous 
SET SOURCE command, or of a SET SOURCE/MODULE=module-name 
command in which a different module name was specified. 

DESCRIPTION 

When used without a qualifier, the CANCEL SOURCE command cancels 
the effect of a previous SET SOURCE command used without a qualifier. 
CANCEL SOURCE does not cancel the effect of a previous SET SOURCE 
/EDIT or SET SOURCE/MODULE=module-name commands. 

See the qualifier descriptions for an explanation of their effects. 

The /EDIT qualifier is needed when the files used for the display of source 
code are different from the files to be edited by means of the EDIT command. 
This is the case with Ada programs. For Ada programs, the (SET, SHOW, 
CANCEL) SOURCE commands affect the search of files used for source 
display (the "copied" source files in Ada program libraries); the (SET, SHOW, 
CANCEL) SOURCE/EDIT commands affect the search of the source files that 
you edit when using the EDIT command. If you use /MODULE with /EDIT, 
the effect of /EDIT is further qualified by /MODULE. 

Related commands: (SET, SHOW) SOURCE, (SET, SHOW) MAX_SOURCE_ 
FILES. 
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CANCEL SOURCE 


EXAMPLE 


DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

SYSTEM::DEVICE:[PROJD] 

[014,015] 

source directory search list for all other modules: 

[PROJA] 

[PROJB] 

[PETER.PROJC] 

DBG> CANCEL SOURCE 
DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

SYSTEM::DEVICE:[PROJD] 

[014,015] 

DBG> CANCEL SOURCE/MODULE=COBOLTEST 
DBG> SHOW SOURCE 

no directory search list in effect 

The CANCEL SOURCE command cancels the effect of a previous SET 
SOURCE command. It does not cancel any source directory search lists 
for specific modules. But the CANCEL SOURCE/MODULE=module-name 
(in this case, COBOLTEST) cancels the source directory search list for that 
module. 
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CANCEL TRACE 


CANCEL TRACE 

Deletes tracepoints. 


FORMAT CANCEL TRACE [address-expressionf, ... 77 


PARAMETERS address-expression 

Specifies a tracepoint to be canceled. Do not use the wildcard character (*). 
Do not specify an address expression when using any of the qualifiers except 
for /EVENT. 


QUALIFIERS /ALL 

Cancels all tracepoints. When using /ALL, do not specify an address 
expression. 

/BRANCH 

Cancels the effect of a previous SET TRACE/BRANCH command. Do not 
specify an address expression with /BRANCH. 

/CALL 

Cancels the effect of a previous SET TRACE/CALL command. Do not specify 
an address expression with /CALL. 

/EVENT=event-name 


Note: /EVENT applies only to Ada and SCAN. See the VAX Ada and VAX 
SCAN documentation for complete information. 

Cancels the effect of a previous SET TRACE/E VENT=event-name command. 
The effect of CANCEL TRACE/EVENT=event-name is symmetrical with the 
effect of SET TRACE/EVENT=event-name. To cancel a tracepoint, specify 
the event name and address expression (if any) exactly as you did with the 
SET TRACE/EVENT command, excluding any WHEN or DO clauses. Event 
names depend on the run-time facility and are identified in Appendix E for 
Ada and SCAN. You can also display the event names associated with the 
current run-time facility by issuing the SHOW EVENT-FACILITY command. 

/EXCEPTION 

Cancels the effect of a previous SET TRACE/EXCEPTION command. Do not 
specify an address expression with /EXCEPTION. 

/INSTRUCTION 

Cancels the effect of a previous SET TRACE/INSTRUCTION command. Do 
not specify an address expression with /INSTRUCTION. 
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CANCEL TRACE 



/LINE 

Cancels the effect of a previous SET TRACE/LINE command. Do not specify 
an address expression with /LINE. 

DESCRIPTION 

The effect of the CANCEL TRACE command is symmetrical with the effect of 
the SET TRACE command. 

To cancel a tracepoint that was established at a specific location with the 

SET TRACE command, specify that same location with the CANCEL 

TRACE command. To cancel tracepoints that were established on a class 
of instructions or events by using a qualifier with the SET TRACE command 
(/CALL, /LINE, /EXCEPTION, /EVENT, and so on), specify that same 
qualifier with the CANCEL TRACE command. 

Generally, you must specify either an address expression or a qualifier, 
but not both. The only exception is with the /EVENT qualifier, which 
requires that you specify an event name and lets you also specify an address 
expression for certain event names. 

Note that the command CANCEL ALL also cancels all tracepoints. 

Related commands: (SET, SHOW) TRACE, (SET, SHOW, CANCEL) BREAK, 
CANCEL ALL. 


EXAMPLES 

Q DBG> CANCEL TRACE MAIN\L00P+10 

This command cancels the tracepoint at the location MAIN\LOOP+10. 

g DBG> CANCEL TRACE/ALL 

This command cancels all tracepoints you have set. 
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CANCEL TYPE/OVERRIDE 


CANCEL TYPE/OVERRIDE 

Cancels the override type established by a previous SET TYPE 
/OVERRIDE command. 

FORMAT 

CANCEL TYPE/OVERRIDE 

PARAMETERS None. 

QUALIFIERS 

/OVERRIDE 

This qualifier must be specified. 

DESCRIPTION 

The CANCEL TYPE/OVERRIDE command sets the current override type to 
"none". As a result, a program location associated with a compiler-generated 
type will be interpreted according to that type. 

Related commands: (SET, SHOW) TYPE/OVERRIDE. 

EXAMPLE 

DBG> CANCEL TYPE/OVERR 

This command cancels the effect of a previous SET TYPE/OVERRIDE 
command. 
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CANCEL WATCH 


CANCEL WATCH 



Cancels watchpoints. 

FORMAT 

CANCEL WATCH [address-expressionf, . . . ]] 


PARAMETERS address-expression 

Specifies a watchpoint to be canceled. With high-level languages, this is 
typically the name of a variable. Do not use the wildcard character (*). 
When using /ALL, do not specify an address expression. 


QUALIFIERS /ALL 

Cancels all watchpoints. When using /ALL, do not specify an address 



expression. 

DESCRIPTION 

The effect of the CANCEL WATCH command is symmetrical with the effect 
of the SET WATCH command. To cancel a watchpoint that was established 
at a specific location with the SET WATCH command, specify that same 
location with the CANCEL WATCH command. Thus, to cancel a watchpoint 
that was set on an entire aggregate, specify the aggregate in the CANCEL 
WATCH command; to cancel a watchpoint that was set on one element of an 
aggregate, specify that element in the CANCEL WATCH command. 

Generally, you must specify either an address expression or a qualifier, 
but not both. The only exception is with the /EVENT qualifier, which 
requires that you specify an event name and lets you also specify an address 
expression for certain event names. 

Note that the CANCEL ALL command also cancels all watchpoints. 

Related commands: (SET, SHOW) WATCH, (SET, SHOW, CANCEL) BREAK, 
(SET, SHOW, CANCEL) TRACE, CANCEL ALL. 


EXAMPLES 

□ DBG> CANCEL WATCH SUB2\T0TAL 

This command cancels the watchpoint at variable TOTAL in module SUB2. 

0 DBG> CANCEL WATCH/ALL 

This command cancels all watchpoints you have set. 
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CANCEL WINDOW 


CANCEL WINDOW 



Permanently deletes a screen window definition. 

FORMAT 

CANCEL WINDOW [wname[, ... 77 


PARAMETERS wname 

Specifies the name of a screen window definition to be canceled. Do not 
use the wildcard character (*). When using /ALL, do not specify a window 
definition name. 


QUALIFIERS /ALL 

Cancels all predefined and user-defined window definitions. When using 



/ALL, do not specify a window definition name. 

DESCRIPTION 

When a window definition is canceled, you may no longer use its name in 
DISPLAY or SET DISPLAY commands. The command does not affect any 
displays. 

Related commands: (SET, SHOW) WINDOW, (SET, SHOW, CANCEL) 
DISPLAY. 


EXAMPLE 


DBG> CANCEL WINDOW MIDDLE 

This command permanently removes the screen window definition MIDDLE. 
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CTRL/C, CTRL/W, CTRL/Y, CTRL/Z 


CTRL/C, 

CTRL/W, CTRL/Y, CTRL/Z 

CTRL/Y interrupts a debugging session. CTRL/C is like CTRL/Y 
unless the program has a CTRL/C service routine. CTRL/Z ends 
a debugging session (like EXIT). CTRL/W refreshes the screen in 
screen mode (like DISPLAY/REFRESH). 

FORMAT 

| CTRL/C | 


| CTRL/W | 


| CTRL/Y | 


| CTRL/Z | 

PARAMETERS None. 

QUALIFIERS 

None. 


DESCRIPTION For an explanation of the CTRL/W and CTRL/Z commands, see the 

descriptions of the DISPLAY/REFRESH and EXIT commands, respectively. 


Unless the system or the user program has defined a CTRL/C service routine, 
CTRL/Y and CTRL/C have the same effect: the image is interrupted but 
unchanged, the terminal type-ahead buffer is purged, and the command 
interpreter receives control. 

You can use the CTRL/Y command to (1) interrupt a debugging session or 
(2) interrupt an executing program in order to then invoke the debugger. 

Interrupting a Debugging Session 

Pressing CTRL/Y interrupts a debugging session and is useful when the 
program is executing an infinite loop that does not have a breakpoint, or 
when you want to interrupt a debugger command that takes a long time 
to complete. You are then at DCL command level. If you then type the 
DCL command DEBUG, control passes to the debugger: you return to the 
debugging session, but execution is suspended and the debugger prompt is 
displayed. You can then issue debugger commands. 

If you type the DCL command CONTINUE after a CTRL/Y interrupt, you 
simply return to the debugging session at the same point in execution where 
you interrupted it. 

Interrupting an Executing Program 

Interrupting program execution with CTRL/Y is useful if your program is 
running without the debugger and you want to invoke the debugger. 

To use this feature, you must, as a minimum, have linked your program with 
the /TRACE qualifier. To reference your program's symbols, you must have 
compiled and linked with the /DEBUG qualifier (in that case, you would use 
the DCL command RUN/NODEBUG to execute the program without the 
debugger). 
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CTRL/C, CTRL/W, CTRL/Y, CTRL/Z 


Related commands: ($) DEBUG, ($) CONTINUE, EXIT, QUIT, DISPLAY 
/REFRESH. 


EXAMPLE 

DBG> GO 


DBG> ICTRL/Yl 
Interrupt 
$ DEBUG 
DBG> 


A debugging session is interrupted with CTRL/Y and resumed with the DCL 
command DEBUG. The debugger prompt indicates that debugger commands 
may now be entered. 
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DECLARE 


DECLARE 

Lets you pass parameters to command procedures 

FORMAT 

DECLARE fnameipkind[,fname:pkind, ... 7 


PARAMETERS fname 

Specifies the formal parameter name. A formal parameter is associated 



with an actual parameter in the order in which the debugger processes the 
parameter declaration. If you specify several formal parameters on a single 
DECLARE command, the leftmost formal parameter is associated with the 
first actual parameter, the next formal parameter is associated with the second, 
and so on. If you use a DECLARE command in a loop, the formal parameter 
is associated with the first actual parameter on the first iteration of the loop; 
the same formal parameter is associated with the second actual parameter on 
the next iteration, and so on. 

Do not specify a null parameter (represented either by two consecutive 
commas or by a comma at the end of the command). 

pkind 

Specifies the parameter type. Valid keywords are: 

ADDRESS Specifies an address expression. It has the same effect as a 

DEFINE/ADDRESS fname = . . . command. 

VALUE Specifies an expression in the current language. It has the same 

effect as a DEFINE/VALUE fname = . . . command. 

COMMAND Specifies a quoted character string. It has the same effect as a 

DEFINE/COMMAND fname = . . . command. 

QUALIFIERS 

None. 

DESCRIPTION 

The DECLARE command can be used only within a command procedure. 

The command associates actual parameters (those on the command line 
following the "(a)") with formal parameters (names inside the command 
procedure). 

Each parameter declaration acts like a DEFINE command: it associates a 
parameter name with a value or other construct. The parameters themselves 
are consistent with those accepted by the DEFINE command and may in fact 
be removed from the symbol table with the DELETE command. For more 
information, see the descriptions of the DEFINE and DELETE commands. 

Related commands: @file-spec, DEFINE, DELETE. 
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DECLARE 


EXAMPLES 

□ $ CREATE DISPLAY.COM 

DECLARE PI:ADDRESS 
EXAMINE PI:PI + 100 


$ RUN PROG 
DBG> ODISPLAY X 
X 

X+4 

X+8 


X+100 

The DECLARE command associates the parameter PI with an address within 
the command procedure DISPLAY.COM. When DISPLAY.COM is invoked 
during the debugging session, address X is examined (as the PI parameter) as 
specified by the EXAMINE P1:P1+100 command. 

Q DBG> FOR I ■ 1 TO V.PARCNT DO (DECLARE X:VALUE; EVALUATE X) 

The DECLARE command is used in a loop. The built-in symbol %PARCNT 
specifies the number of actual parameters passed to the command procedure. 
The DECLARE command associates each parameter with a value and the 
EVALUATE command obtains that value. 
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DEFINE 


DEFINE 

Defines one or more symbols for the duration of the debugging 
session. 

FORMAT 

DEFINE symbohparameter[,symbohparameter,...] 


PARAMETERS symbol 

Specifies the name of a symbol to be defined. Symbols can be composed of 



alphanumeric characters and underscores. The debugger converts lowercase 
alphabetic characters to uppercase. The first character must not be a number. 
The symbol must be no more than 31 characters long. 

parameter 

Depends on the qualifier specified. 

QUALIFIERS 

/ADDRESS 

Specifies that the defined symbol is an abbreviation for an address expression. 
In this case, parameter is an address expression. DEFINE/ADDRESS is the 
default. 

/COMMAND 

Specifies that the defined symbol is to be treated as a new debugger 
command. In this case, parameter is a quoted character string. This qualifier 
provides, in simple cases, essentially the same capability as the DCL 
command "symbol^string." To define complex commands, you may need 
to use command procedures with formal parameters. For more information 
on declaring parameters to command files (or procedures), see the description 
of the DECLARE command. 

/LOCAL 

Specifies that the definition remain local to the command procedure in which 
the DEFINE command is issued. The defined symbol is not visible at the 
debugger command level. By default, a symbol defined within a command 
procedure is visible outside that procedure. 

/VALUE 

Specifies that the defined symbol is an abbreviation for a value. In this case, 
parameter is a language expression in the current language. 

DESCRIPTION 

The DEFINE/ADDRESS command lets you define a symbol to refer to 
an address in your program. For example, you can define a symbol for a 
nonsymbolic program location or for a symbolic program location having a 
long path-name prefix. Then, you can refer to that program location by the 
newly defined symbol. /ADDRESS is the default definition qualifier. 
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DEFINE 


The DEFINE/COMMAND command lets you define abbreviations for 
debugger commands or even define new commands, either from the debugger 
command level or from command procedures. 

The DEFINE/VALUE command lets you assign a symbolic name to a value 
(or the result of evaluating a language expression). 

Use the /LOCAL qualifier to confine symbol definitions to command 
procedures. By default, defined symbols are global (visible outside the 
command procedure). 

If you plan to issue several DEFINE commands with the same qualifier, you 
can first use the SET DEFINE command to establish a new default qualifier 
(for example, SET DEFINE COMMAND makes the DEFINE command behave 
like DEFINE/COMMAND). Then you do not have to use that qualifier with 
the DEFINE command. You can override the current default qualifier for the 
duration of a single DEFINE command by specifying another qualifier. 

In symbol translation, the debugger searches symbols you define during 
the debugging session first. So if you define a symbol that already exists in 
your program, the debugger translates the symbol according to its defined 
definition, unless you specify a path-name prefix. 

When a symbol is redefined, the previous definition is canceled, even if 
different qualifiers were used with the DEFINE command. If you use the 
SET IMAGE command to establish a new current image, all definitions 
created with the DEFINE/ADDRESS and DEFINE/VALUE commands are 
deleted (definitions created with the DEFINE/COMMAND and DEFINE/KEY 
commands are retained, however). 

Use the SHOW SYMBOL/DEFINED * command to determine the equivalence 
value of a symbol. 

Use the DELETE command to cancel a symbol definition. 

Related commands: SHOW DEFINE, SHOW SYMBOL/DEFINED, DELETE, 
SET IMAGE. 


EXAMPLES 

Q DBG> DEFINE CHK=MAIN\L00P+10 

This command assigns the symbol CHK to the address MAIN\LOOP+10. 

Q DBG> DEFINE/VALUE C0UNTER=0 

DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1) 

The first command assigns a value of 0 to the symbol COUNTER. The second 
command tells the debugger to increment the value of the symbol COUNTER 
by 1 every time address R is encountered. In other words, this example tells 
the debugger to count the number of calls to R. 

0 DBG> DEFINE/COMMAND BRE = "SET BREAK" 

This command assigns the symbol BRE to the debugger command SET 
BREAK. 
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DEFINE/KEY 


Assigns a string to a function key. 


FORMAT DEFINE/KEY key-name "equiv-string 


PARAMETERS key-name 

Specifies a function key to be assigned a string. Valid key names are the 
following: 


Key-name 


LK201 

VTIOO-type 

VT52-type 

PF1 


PF1 

PF1 

Blue 

PF2 


PF2 

PF2 

Red 

PF3 


PF3 

PF3 

Black 

PF4 


PF4 

PF4 


KPO, KP1, . 

. . ,KP9 

Keypad 0, ... ,9 

Keypad 0, ... ,9 

Keypad 0, ... ,9 

PERIOD 


Keypad period (.) 

Keypad period (.) 


COMMA 


Keypad comma (,) 

Keypad comma (,) 


MINUS 


Keypad minus (-) 

Keypad minus (-) 


ENTER 


ENTER 

ENTER 

ENTER 

El 


Find 



E2 


Insert Here 



E3 


Remove 



E4 


Select 



E5 


Prev Screen 



E6 


Next Screen 



HELP 


Help 



DO 


Do 



F6, F7, . . . 

, F20 

F6, F7.F20 




equiv-string 

Specifies the string to be processed when the specified key is pressed. 
Typically, this is one or more debugger commands. If the string includes any 
spaces or non-alphanumeric characters (for example, a semicolon separating 
two commands) enclose the string in quotation marks. 


QUALIFIERS /[NOJECHO 

Controls whether the command line is displayed after the key has 
been pressed. The default is /ECHO. Do not use /NOECHO with 
/NOTERMINATE. 
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DEFINE/KEY 


/[NO]IF_STATE=(state-name[, . . . ]) 

Specifies one or more states to which a key definition applies. /IF_STATE 
assigns the key definition to the specified states. You may specify predefined 
states, such as DEFAULT and GOLD, or user-defined states. A state name 
can be any appropriate alphanumeric string. /NOIF_STATE (default) assigns 
the key definition to the current state. 

/[NOJLOCK—STATE 

Controls how long the state set by /SET_STATE remains in effect after the 
specified key is pressed. /LOCK —STATE causes the state to remain in effect 
until it is changed explicitly (for example, with a SET KEY/STATE command). 
/NOLOCK—STATE (default) causes the state to remain in effect only until 
the next terminator character is typed, or until the next defined function key 
is pressed. 

/[NO]LOG 

Controls whether a message is displayed indicating that the key definition has 
been successfully created. /LOG (default) displays the message. 

/[NOJSET—S TATE=sta te-name 

Controls whether pressing the key changes the current key state. /SET- 
STATE causes the current state to change to the specified state when you 
press the key. /NOSET—STATE (default) causes the current state to remain in 
effect. 

/[NOJTERMINATE 

Controls whether the specified string is to be terminated (processed) when 
the key is pressed. /TERMINATE causes the string to be terminated when 
the key is pressed. /NOTERMINATE (default) allows you to press other keys 
before terminating the string by pressing the RETURN key. 


DESCRIPTION Keypad mode must be enabled (SET MODE KEYPAD) before you can use 
this command. Keypad mode is enabled by default. 

The DEFINE/KEY command lets you assign a string to a function key, 
overriding any predefined function that was bound to that key (the predefined 
key functions are listed in Appendix B). When you then press the key, the 
debugger enters the currently associated string into your command line. The 
DEFINE/KEY command is like the DCL DEFINE/KEY command. 

On VT52 and VTlOO-series terminals, the function keys you can use include 
all of the numeric keypad keys. VT-200 series terminals and Micro VAX 
workstations have the LK201 keyboard. On LK201 keyboards, the function 
keys you can use include all of the numeric keypad keys, the non-arrow keys 
of the editing keypad (Find, Insert Here, and so on), and keys F6 through F20 
at the top of the keyboard. 

A key definition remains in effect until you redefine the key, issue the 
DELETE/KEY command for that key, or exit the debugger. You can include 
key definitions in a command procedure, such as your debugger initialization 
file. 

The /IF— STATE qualifier lets you increase the number of key definitions 
available on your terminal. The same key can be assigned any number of 
definitions as long as each definition is associated with a different state. 
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By default, the current key state is the "DEFAULT" state. The current state 
may be changed with the SET KEY/STATE command, or by pressing a key 
that causes a state change (a key that was defined with the DEFINE/KEY 
/LOCK—STATE/STATE qualifier combination). 

Related commands: DELETE/KEY, SHOW KEY, SET KEY. 


EXAMPLES 

□ DBG> SET KEY/STATE=GOLD 

7.DEBUG-I-SETKEY, keypad state has been set to GOLD 
DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX" 

XDEBUG-I-DEFKEY, GOLD key KP9 has been defined 

The SET KEY command establishes GOLD as the current key state. The 
DEFINE/KEY command assigns the SET RADIX/OVERRIDE HEX command 
to keypad key 9 for the current state (GOLD). The command is processed 
when key is pressed. 

S DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK '/.LINE " 

XDEBUG-I-DEFKEY, BLUE key KP9 has been defined 

This command assigns the unterminated command string "SET BREAK 
%LINE " to keypad key 9, for the BLUE state. After pressing keypad key 9, 
you can enter a line number and then press the RETURN key to process the 
SET BREAK command. 

E DBG> SET KEY/STATE=DEFAULT 

%DEBUG-I-SETKEY, keypad state has been set to DEFAULT 
DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 "" 

'/.DEBUG -1 - DEFKEY, DEFAULT key F12 has been defined 

The SET KEY command establishes DEFAULT as the current state. The 
DEFINE/KEY command makes key F12 (LK201 keyboard) a state key. 
Pressing FI2 while in the DEFAULT state causes the current state to become 
RED. The key definition is not terminated and has no other effect (a null 
string is assigned to FI2). After pressing FI2, you can issue "RED" commands 
by pressing keys that have definitions associated with the RED state. 
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DELETE 

Deletes a symbol definition from the DEFINE symbol table. 

FORMAT 

DELETE [symbol-name[, ... 77 


PARAMETERS symbol-name 



Specifies a symbol whose definition is to be deleted from the DEFINE symbol 
table. Do not use the wildcard character (*). When using /ALL, do not 
specify a symbol name. If you use /LOCAL, the symbol specified must have 
been previously defined with the DEFINE/LOCAL command. If you do not 
specify /LOCAL, the symbol specified must have been previously defined 
with the DEFINE command without the /LOCAL qualifier. 

QUALIFIERS 

/ALL 

Deletes all global DEFINE definitions. If you also specify /LOCAL, deletes 
all local DEFINE definitions associated with the current command procedure 
(but not the global DEFINE definitions). When using /ALL, do not specify a 
symbol name. 

/LOCAL 

Deletes the (local) definition of the specified symbol from the current 
command procedure. The symbol must have been previously defined with 
the DEFINE/LOCAL command. 

DESCRIPTION 

The DELETE command deletes either a global DEFINE symbol or a local 
DEFINE symbol. A global DEFINE symbol is a symbol defined with the 
DEFINE command without the /LOCAL qualifier. A local DEFINE symbol 
is a symbol defined in a debugger command procedure with the DEFINE 
/LOCAL command, so that its definition is confined to that command 
procedure. The DELETE command is identical to the UNDEFINE command. 

Related commands: DEFINE. 

EXAMPLE 


DBG> DEFINE X = INARR, Y = 
DBG> DELETE X.Y 

OUTARR 

The DEFINE command defines X and Y as global symbols corresponding to 
INARR and OUTARR, respectively. The DELETE command deletes these two 
symbol definitions from the global symbol table. 

DBG> DELETE/ALL/LOCAL 

The DELETE/ALL/LOCAL commmand deletes all local symbol definitions 
from the current command procedure. 
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DELETE/KEY 


Deletes key definitions that have been established with the DEFINE 
/KEY command. 


FORMAT DELETE/KEY [key-name] 


PARAMETERS key-name 

Specifies a key whose definition is to be deleted. Do not use the wildcard 
character (*). When using /ALL, do not specify a key name. Valid key 
names are: 


Key-name 


LK201 

VT100-type 

VT52-type 

PF1 


PF1 

PF1 

Blue 

PF2 


PF2 

PF2 

Red 

PF3 


PF3 

PF3 

Black 

PF4 


PF4 

PF4 


KPO, KP1,. 

. . ,KP9 

Keypad 0, ... ,9 

Keypad 0, ... ,9 

Keypad 0, ... ,9 

PERIOD 


Keypad period (.) 

Keypad period (.) 


COMMA 


Keypad comma (,) 

Keypad comma (,) 


MINUS 


Keypad minus (-) 

Keypad minus (-) 


ENTER 


ENTER 

ENTER 

ENTER 

El 


Find 



E2 


Insert Here 



E3 


Remove 



E4 


Select 



E5 


Prev Screen 



E6 


Next Screen 



HELP 


Help 



DO 


Do 



F6, F7, . . . 

, F20 

F6, F7.F20 




QUALIFIERS /ALL 

Deletes all key definitions in the specified state. When using /ALL, do not 
specify a key name. If you do not specify a state, all key definitions in the 
current state are deleted. Use the /STATE qualifier to specify one or more 
states. 
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/[NOJLOG 

Controls whether a message is displayed indicating that the specified key 
definitions have been deleted. /LOG (default) displays the message. 












DELETE/KEY 


/[NO]STATE=(state-name [, . . . ]) 

Selects one or more states for which a key definition is to be deleted. /STATE 
deletes key definitions for the specified states. You may specify predefined 
key states, such as DEFAULT and GOLD, or user-defined states. A state 
name can be any appropriate alphanumeric string. /NOSTATE (default) 
deletes the key definition for the current state only. 

By default, the current key state is the "DEFAULT" state. The current state 
may be changed with the SET KEY/STATE command, or by pressing a key 
that causes a state change (a key that was defined with the DEFINE/KEY 
/LOCK_STATE/STATE qualifier combination). 


DESCRIPTION Keypad mode must be enabled (SET MODE KEYPAD) before you can use 

this command. Keypad mode is enabled by default. 

The DELETE/KEY command is like the DCL DELETE/KEY command and 
has the same effect as the (debugger) UNDEFINE/KEY command. 

Related commands: DEFINE/KEY, SHOW KEY, SET KEY. 


EXAMPLES 

□ DBG> DELETE/KEY KP4 

‘/.DEBUG -1-DELKEY, DEFAULT key KP4 has been deleted 

This command deletes the key definition for keypad key KP4 in the state last 
set by the SET KEY command (by default, this is the DEFAULT state). 

Q DBG> DELETE/KEY/STATE=(BLUE,RED) COMMA 

‘/.DEBUG-1-DELKEY, BLUE key COMMA has been deleted 
‘/.DEBUG-I-DELKEY, RED key COMMA has been deleted 


This command deletes the key definition for keypad key COMMA in the 
BLUE and RED states. 
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DEPOSIT 

Changes the value of a variable or the contents of a program 
location. 

FORMAT 

DEPOSIT address-expression = language-expression 


PARAMETERS address-expression 

Specifies the location into which the value of the language expression is to be 



deposited. With high-level languages, address-expression is typically the name 
of a variable. 

language-expression 

Specifies the value to be deposited. You may specify any source language 
expression in the currently set language. 

When the DEPOSIT command is executed, the expression is evaluated in the 
syntax of the source language. The value of the expression is then converted 
to the type associated with the address expression and placed at the location 
denoted by the address expression. 

If the expression is an ASCII string or a VAX/VMS assembly-language 
instruction, you must enclose it in quotation marks or apostrophes. 

QUALIFIERS 

/ASCIC 

Deposits a counted ASCII string with a 1-byte count into the specified 
location. This is an ASCII string preceded by a 1-byte count field that gives 
the length of the string. /AC is also accepted. 

/ASCID 

Deposits an ASCII string into the address given by a string descriptor that is 
at the specified location. The expression on the right-hand side of the equal 
sign must be a string. The specified location must contain a string descriptor. 
If the string lengths do not match, the string is either truncated on the right 
or padded with blanks on the right. /AD is also accepted. 

/ASCII.n 

Deposits n bytes of a string into the specified location. The expression on the 
right-hand side of the equal sign must be a string. If its length is not n, the 
string is truncated or padded with blanks on the right. If n is omitted, the 
actual length of the data item at the specified location is used. 

/ASCIW 

Deposits a counted ASCII string with a 1-word count into the specified 
location. This is an ASCII string preceded by a 2-byte count field that gives 
the length of the string. /AW is also accepted. 
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/ASCIZ 

Deposits a zero-terminated ASCII string into the specified location. The 
expression on the right-hand side of the equal sign must be a string. 

The string is deposited into the specified location followed by a zero byte 
indicating the end of the string. /AZ is also accepted. 

/BYTE 

Deposits a 1-byte integer into the specified location. 

/D—FLOAT 

Converts the expression on the right-hand side of the equal sign to the 
D_floating type (length 8 bytes) and deposits the result into the specified 
location. Values of type D_floating may range from .29*10~ 38 to l.7*10 38 with 
approximately 16 decimal digits precision. 

/DATE-TIME 

Converts a string representing a date and time (for example, 31-MAR-1985 
21:08:47.15) to the VAX/VMS internal format for date and time and deposits 
that quadword into the specified location. 

/FLOAT 

Converts the expression on the right-hand side of the equal sign to the 
F_floating type (length 4 bytes) and deposits the result into the specified 
location. Values of type F__floating may range from .29*10~ 38 to 1.7*1(P 8 with 
approximately 7 decimal digits precision. 

/G-FLOAT 

Converts the expression on the right-hand side of the equal sign to the 
G —floating type (length 8 bytes) and deposits the result into the specified 
location. Values of type G_floating may range from .56*10~ 308 to .9 # 10 308 
with approximately 15 decimal digits precision. 

/H—FLOAT 

Converts the expression on the right-hand side of the equal sign to the 
H —floating type (length 16 bytes) and deposits the result into the specified 
location. Values of type H_floating may range from .84*10~ 4932 to . 59*10 4932 
with approximately 33 decimal digits precision. 

/INSTRUCTION 

Deposits a VAX/VMS assembly-language instruction into the specified 
location. The expression on the right-hand side of the equal sign must be 
a string representing a VAX/VMS instruction. 

/LONGWORD 

Deposits a longword integer (length 4 bytes) into the specified location. 

/OCTAWORD 

Deposits an octaword integer (length 16 bytes) into the specified location. 
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/PACKED.n 

Converts the expression on the right-hand side of the equal sign to a packed 
decimal representation (length n nibbles) and deposits the resulting value into 
the specified location. 

/QUADWORD 

Deposits a quadword integer (length 8 bytes) into the specified location. 

/TASK 

Note: /TASK applies only to Ada programs. 

Deposits an Ada task value (a task name, or a task ID such as %TASK 3) into 
the specified location. 

/TYPE= (type-expression) 

Converts the expression to be deposited to the type denoted by type- 
expression (the name of a variable or data type), then deposits the resulting 
value into the specified location. 

/WORD 

Deposits a word integer (length 2 bytes) into the specified location. 


DESCRIPTION In general, the DEPOSIT command may be used to change the contents of 

any memory location in your program. Typically, the command is used to 
change the value of a program variable. 

The DEPOSIT command is like an assignment statement in most 
programming languages. The value specified to the right of the equal sign is 
deposited into the location specified to the left of the equal sign (note that for 
Ada and PASCAL, you can use instead of in the command syntax). 
Type conversion, if necessary, is done according to the rules of the currently 
set language. 

The debugger knows the compiler-generated type of a variable (whether it is 
an integer, real, string, array, record, and so on), as well as any dimensional 
constraints that apply to that variable. When you use the DEPOSIT 
command, the debugger checks that the value assigned to a variable is 
consistent with the data type and dimensional constraints of the variable. 

By using qualifiers with the DEPOSIT command, you can override the type 
associated with a program location in order to deposit data of a different type. 

The DEPOSIT command sets the current entity built-in symbols %CURLOC 
and period (.) to the location denoted by the address expression specified. 
Logical predecessors (%PREVLOC and circumflex (~)) and successors 
(%NEXTLOC and pressing the RETURN key) are based on the value of 
the current entity symbol. 

Related commands: EXAMINE, EVALUATE, (SET, SHOW, CANCEL) RADIX, 
(SET, SHOW) TYPE, CANCEL TYPE/OVERRIDE. 
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EXAMPLES 

Q DBG> DEPOSIT 1=7 

This command deposits the value 7 into the integer variable I. 

B DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 24.80 

This command deposits the value of the expression CURRENT-WIDTH + 
24.80 into the real variable WIDTH. 

g DBG> DEPOSIT STATUS = FALSE 

This command deposits the value FALSE into the boolean variable STATUS. 

Q DBG> DEPOSIT PART.NUMBER = "WG-7619.3-84" 

This command deposits the string WG-7619.3-84 into the string variable 
PART-NUMBER. 

g DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 

This command deposits the value 02172 into component ZIPCODE of record 
EMPLOYEE. 

2 DBG> DEPOSIT ARR(8) = 35 
DBG> DEPOSIT “ = 14 

The first DEPOSIT command deposits the value 35 into element 8 of array 
ARR. As a result, element 8 becomes the current entity. The second command 
deposits the value 14 into the logical predecessor of element 8, namely 
element 7. 

Q DBG> FOR I = 1 TO 4 DO (DEPOSIT ARR(I) = 0) 

This command deposits the value 0 into elements 1 through 4 of array ARR. 

[j] DBG> DEPOSIT COLOR = 3 

'/.DEBUG-E-0PTN0TALL0W, operator "DEPOSIT" not allowed on given data type 

The debugger alerts you when you try to deposit data of the wrong type (in 
this case, an integer) into a variable. The E (error) message severity indicates 
that the debugger does not make the assignment. 

g DBG> DEPOSIT VOLUME = - 100 

'/.DEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near 

The debugger alerts you when you try to deposit an out-of-bounds value 
into a variable (in this case a negative value). The I (informational) message 
severity indicates that the debugger does make the assignment. 

EE DBG> DEPOSIT/BYTE WORK = '/.HEX 212 

This command deposits the expression %HEX 212 into location WORK and 
converts it to a byte integer. 

ED DBG> DEP0SIT/0CTAW0RD BIGINT = 111222333444555 

This command deposits the expression 111222333444555 into location 
BIGINT and converts it to an octaword integer. 
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EE DBG> DEPOSIT/FLOAT BIGFLT = 1.11949*10**35 

This command converts 1.11949*10**35 to an F_floating type value and 
deposits it into location BIGFLT. 

EE DBG> DEPOSIT/ASCII:10 W0RK+20 * ’abcdefghij’ 

This command deposits the string abcdefghij into location WORK+20. 

EE DBG> DEPOSIT/INSTR SUB2+2 = ’MOVL #20A,R0’ 

This command deposits the instruction MOVL #20A,R0' into location 
SUB2+2. 

EE DBG> DEPOSIT/TASK VAR = ‘/.TASK 2 
DBG> EXAMINE/HEX VAR 
SAMPLE.VAR: 0016A040 
DBG> EXAMINE/TASK VAR 
SAMPLE.VAR: XTASK 2 


The DEPOSIT command deposits the Ada task value %TASK 2 into location 
VAR. The subsequent EXAMINE commands display the contents of VAR in 
hexadecimal format and as a task value, respectively. 
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DISABLE AST 



Disables the delivery of ASTs (asynchronous system traps) in your 
program. 

FORMAT 

DISABLE AST 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The DISABLE AST command prevents interrupts from occurring while 
the debugger is running. Note that this does not prevent interrupts from 
occurring while the program is running. The ENABLE AST command re¬ 
enables the delivery of ASTs, including any pending ASTs (ASTs waiting to 
be delivered). 

Related commands: (ENABLE, SHOW) AST. 


EXAMPLE 


DBG> DISABLE AST 

DBG> SHOW AST 

ASTs are disabled 

The DISABLE AST disables the delivery of ASTs, as confirmed with the 
SHOW AST command. 
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DISPLAY 

Modifies an existing screen display. 


FORMAT 

DISPLAY [disp-name [AT wspec][dkind]][, . 



PARAMETERS disp-name 

Specifies a screen display to be displayed. You may specify any of the 
following: 

• A predefined display: SRC, OUT, PROMPT, INST, REG 

• A display previously created with the SET DISPLAY command 

• A pseudo-display name: %CURDISP, %CURSCROLL, %NEXTDISP, 
%NEXTINST, %NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE 

You must specify this parameter unless you use /GENERATE (parameter 
optional), or /REFRESH (parameter not allowed). 

You may specify more than one display, each with an optional window 
specification (wspec) and display kind (dkind). 

wspec 

Specifies the screen window at which the display is to be positioned if you 
want to change the position. You may specify any of the following: 

• A predefined window. For example, RH1 (right top half). See 
Appendix C. 

• A window definition previously established with the SET WINDOW 
command. 

• A window specification of the form (start-line, line-count [,start-column, 
column-count]). The specification can include expressions which may 
be based on the built-in symbols %PAGE and % WIDTH (for example, 
% WIDTH/4). 

If you omit the wspec parameter, the screen position of the display is not 
changed. 
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QUALIFIERS 


dkind 

Specifies the new display kind if you want to change the kind of display. 
Valid keywords are the following: 

DO (cmd-list) Specifies an automatically updated output display. 

The commands in cmd-list are executed each 
time the debugger gains control. Their output 
forms the contents of the display. 

INSTRUCTION Specifies an instruction display. If selected as 

the current instruction display with the SELECT 
/INSTRUCTION command, it will display the 
output from subsequent EXAMINE/INSTRUCTION 
commands. 

Specifies an automatically updated instruction 
display. The command specified must be 
an EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 

Specifies an output display. If selected as the 
current output display with the SELECT/OUTPUT 
command, it will display any debugger output 
that is not directed to another display. If selected 
as the current input display with the SELECT 
/INPUT command, it will echo debugger input. 

If selected as the current error display with 
the SELECT/ERROR command, it will display 
debugger diagnostic messages. 

Specifies an automatically updated register 
display. The display is updated each time the 
debugger gains control. 

Specifies a source display. If selected as 
the current source display with the SELECT 
/SOURCE command, it will display the output 
from subsequent TYPE or EXAMINE/SOURCE 
commands. 

SOURCE (command) Specifies an automatically updated source display. 

The command specified must be a TYPE or 
EXAMINE/SOURCE command. The source 
display is updated each time the debugger gains 
control. 

You cannot change the display kind of the PROMPT display. 


INSTRUCTION (command) 

OUTPUT 

REGISTER 

SOURCE 


/CLEAR 

Erases the entire contents of a specified display. 

/[NOJDYNAMIC 

Controls whether a display automatically adjusts its window dimensions 
proportionally when a SET TERMINAL command is issued. By default 
(/DYNAMIC), all user-defined and predefined displays, except register 
displays, adjust their dimensions automatically. A register display maintains 
its window dimensions and location when the screen height or width are 
changed. 
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/GENERATE 

Regenerates the contents of a specified display. Only automatically generated 
displays are regenerated. These include DO displays, register displays, 
source (cmd-list) displays, and instruction (cmd-list) displays. The debugger 
automatically regenerates all these kinds of displays before each prompt. If 
no display is specified, regenerates the contents of all automatically generated 
displays. 

/HIDE 

Places a specified display at the bottom of the display pasteboard. This makes 
visible any display previously hidden by the specified display. It also hides 
the specified display behind any other displays that share the same region of 
the screen. You cannot hide the PROMPT display. 

/HIDE has the same effect as /PUSH. 

/[NOJMARK—CHANGE 

Controls whether the lines that change in a DO display each time it is 
automatically updated are marked. When you use /MARK—CHANGE, any 
lines in which some contents have changed since the last time the display 
was updated are highlighted in reverse video. This qualifier is particularly 
useful when you want any variables in an automatically updated display to 
be highlighted when they change. 

/NOMARK—CHANGE (default) specifies that any lines that change in DO 
displays are not to be marked. This qualifier cancels the effect of a previously 
issued /MARK-CHANGE qualifier on the specified display. 

This qualifier is not applicable to other kinds of displays. 

/[NO]POP 

Controls whether a specified display is placed at the top of the display 
pasteboard, ahead of any other displays but behind the PROMPT display. By 
default (/POP), the display is placed at the top of the pasteboard and hides 
any other displays that share the same region of the screen, except for the 
PROMPT display. This is the default action of the DISPLAY command. 

/NOPOP preserves the order of all displays on the pasteboard (same effect as 
/NOPUSH). 

/[NOJPUSH 

/PUSH has the same effect as /HIDE. /NOPUSH preserves the order of all 
displays on the pasteboard (same effect as /NOPOP). 

/REFRESH 

Refreshes the terminal screen. If you use this qualifier, do not use any 
command parameters. 






DISPLAY 


/REMOVE 

Marks the display as being removed from the display pasteboard, so it will 
not be shown on the screen unless you explicitly request it with another 
DISPLAY command. Although a removed display is not visible on the screen, 
it still exists and its contents are preserved. You cannot remove the PROMPT 
display. 

/SIZE:n 

Changes the maximum size of a display to n lines. If more than n lines are 
written to the display, the oldest lines are lost as the new lines are added. If 
you omit this qualifier, the maximum size is not changed. 

For an output or DO display, /SIZE:n specifies that the display should 
hold the n most recent lines of output. For a source or instruction display, 
n gives the number of source lines or lines of instructions that can be 
placed in the memory buffer at any one time. However, you can scroll a 
source display over the entire source code of the module whose code is 
displayed (source lines are paged into the buffer as needed). Similarly, you 
can scroll an instruction display over all of the instructions of the routine 
whose instructions are displayed (instructions are decoded from the image as 
needed). 


DESCRIPTION The DISPLAY command performs a variety of functions. Its major function 
is to show the display you have requested. The display is placed on top of 
the display pasteboard, ahead of the other displays but behind the PROMPT 
display, which cannot be hidden. The specified display thus becomes visible, 
and the portions of any displays that share the same region of the screen are 
hidden (although these displays still exist). 

With certain qualifiers, you can use this command to remove displays from 
the terminal screen or to refresh the entire screen. You can also use this 
command to change the display's screen window, to change its maximum size 
in lines, or to change its kind or debug command list. 

See Appendix B for keypad-key definitions associated with the DISPLAY 
command. 

Related commands: (SET, SHOW, CANCEL) DISPLAY, (SET, SHOW, 
CANCEL) WINDOW, SELECT, EXPAND, MOVE, (SET, SHOW) TERMINAL. 


EXAMPLES 

Q DBG> DISPLAY REG 

This command shows the predefined register display, REG, at its current 
window location. 

2 DBG> DISPLAY NEWDISP AT RT2 
DBG> SELECT/INPUT NEWDISP 

The DISPLAY command shows the user-defined display NEWDISP at the 
right middle third of the screen. The SELECT/INPUT command selects 
NEWDISP as the current input display. NEWDISP will echo debugger input. 
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EDIT 

Invokes the editor established with the SET EDITOR command. If 
no SET EDITOR command was issued, invokes the VAX Language- 
Sensitive Editor, if that editor is installed on your system. 

FORMAT 

EDIT [[module-name \] line-number] 


PARAMETERS module-name 

Specifies the name of the module whose source file is to be edited. If you 



specify a module name, you must also specify a line number. If you omit the 
module name parameter, the source file whose code appears in the current 
source display is chosen for editing. 

line-number 

A positive integer that specifies the source line on which the editor's cursor 
is to be initially placed. If you omit this parameter, the cursor is initially 
positioned at the start of the source line that is centered in the debugger's 
current source display, or at the start of line 1 if the editor was set to 
/NOSTART—POSITION (see the SET EDITOR command description). 

QUALIFIERS 

/[NOJEXIT 

Controls whether you end the debugging session prior to invoking the 
debugger. If you specify /EXIT, the debugging session is terminated and the 
editor is then invoked. If you specify /NOEXIT (default), the editing session 
is spawned in a subprocess and you return to your debugging session after 
exiting from the editor. 

DESCRIPTION 

If you have not specified an editor with the SET EDITOR command, the 
EDIT command invokes the VAX Language-Sensitive Editor in a spawned 
subprocess (if the VAX Language-Sensitive Editor is installed on your system). 
The typical (default) way to use the EDIT command is not to specify any 
parameters. In this case, the editing cursor is initially positioned at the start 
of the line that is centered in the currently selected debugger source display 
(the current source display). 

The SET EDITOR command provides options for invoking different editors, 
either in a subprocess or through a callable interface. 

Related commands: (SET, SHOW) EDITOR, (SET, SHOW, CANCEL) 
SOURCE. 
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EXAMPLES 

Q DBG> EDIT 

The EDIT command spawns the VAX Language-Sensitive Editor in a 
subprocess to edit the source file whose code appears in the current source 
display. The editing cursor will be positioned at the start of the line that was 
centered in the source display. 

E DBG> EDIT SWAP\12 

The EDIT command spawns the VAX Language-Sensitive Editor in a 
subprocess to edit the source file containing the module SWAP. The editing 
cursor will be positioned at the start of source line 12. 

E DBG> SET EDITOR/CALLABLE.EDT 
DBG> EDIT 


The SET EDITOR/CALLABLE _EDT command establishes that EDT is the 
default editor and is invoked through its callable interface (rather than 
spawned in a subprocess). The EDIT command invokes EDT to edit the 
source file whose code appears in the current source display. The editing 
cursor will be positioned at the start of source line 1, because the default 
qualifier /NOSTART_POSITION applies to EDT. 
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ENABLE AST 



Enables the delivery of asynchronous system traps (ASTs) in your 
program. 

FORMAT 

ENABLE AST 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The ENABLE AST command enables the delivery of asynchronous system 
traps (ASTs) while the debugger is running, including any pending ASTs 
(ASTs waiting to be delivered). Delivery of ASTs is initially enabled by 
default. 

Related commands: (DISABLE, SHOW) AST. 

EXAMPLE 


DBG> ENABLE AST 

DBG> SHOW AST 

ASTs are enabled 

The ENABLE AST command enables the delivery of ASTs, as confirmed with 
the SHOW AST command. 
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EVALUATE 



Evaluates a language expression in the currently set language. 

FORMAT 

EVALUATE !anguage-expression[ f ... 7 


PARAMETERS expression 



Specifies any valid expression in the source language. 

QUALIFIERS 

/CONDITION-VALUE 

Specifies that the expression be interpreted as a VAX/VMS condition value 
(the kind of condition value you would specify using the condition-handling 
mechanism). The message text corresponding to that condition value is then 
displayed. The specified value must be an integer value. 

/BINARY 

Specifies that the result be displayed in binary radix. 

/DECIMAL 

Specifies that the result be displayed in decimal radix. 

/HEXADECIMAL 

Specifies that the result be displayed in hexadecimal radix. 

/OCTAL 

Specifies that the result be displayed in octal radix. 

DESCRIPTION 

The debugger interprets the parameter specified in an EVALUATE command 
as a source-language expression, evaluates it in the syntax of the source 
language, and displays its value as a literal in the source language. 

If an expression contains symbols with different compiler-generated types, the 
debugger uses the type-conversion rules of the current language to evaluate 
the expression. 

If you specify a radix command qualifier, the debugger displays the value of 
the expression as a literal in that radix. A radix command qualifier does not, 
however, affect how the debugger interprets a literal. 

Debugger support for language-specific operators and constructs is described 
in Appendix E. 

Related commands: EVALUATE/ADDRESS, (SET, SHOW, CANCEL) RADIX, 
(SET, SHOW, CANCEL) TYPE, SHOW SYMBOL. 
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EXAMPLES 

Q DBG> EVALUATE 100.34 * (14.2 + 7.9) 
2217.514 


This command uses the debugger as a calculator by multiplying 100.34 by 
(14.2 + 7.9). 


Q DBG> EVALUATE/OCTAL X 
00000001512 

This command evaluates the symbol X and displays the result in octal radix. 

gj DBG> EVALUATE TOTAL + CURR.AMOUNT 
8247.20 

This command evaluates the sum of the values of two real variables, TOTAL 
and CURR-AMOUNT. 

Q DBG> DEPOSIT WILLING = TRUE 
DBG> DEPOSIT ABLE = FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 


The EVALUATE command evaluates the logical AND of the current values of 
two boolean variables, WILLING and ABLE. 

g DBG> EVALUATE COLOR’FIRST 
RED 


(Ada example). This command evaluates the first element of the enumeration 
type COLOR. 
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EVALUATE/ADDRESS 



Evaluates an address expression and displays the result as a virtual 
memory address. 

FORMAT 

EVALUATE/ADDRESS address-expressionf, ... 7 


PARAMETERS address-expression 

Specifies an address expression of any valid form (for example, a routine 



name, a variable name, a label, a line number, and so on). 

QUALIFIERS 

/BINARY 

Specifies that the result be displayed in binary radix. 

/DECIMAL 

Specifies that the result be displayed in decimal radix. 

/HEXADECIMAL 

Specifies that the result be displayed in hexadecimal radix. 

/OCTAL 

Specifies that the result be displayed in octal radix. 

DESCRIPTION 

The EVALUATE/ADDRESS command lets you determine the virtual address 
designated by an address expression. 

By default, the address is displayed in hexadecimal radix for BLISS and 
MACRO and decimal radix for other languages. You can use a radix 
command qualifier to display address values in some other radix. 

If a variable is stored in a register instead of virtual memory, the EVALUATE 
/ADDRESS command returns the name of the register. 

Related commands: EVALUATE, (SET, SHOW, CANCEL) RADIX, SHOW 
SYMBOL /ADDRESS. 


EXAMPLES 

Q DBG> EVALUATE/ADDRESS MODNAMEV/.LINE 110 
3942 

This command determines the value of the address expression 
MODNAME\%LINE 110. 

Q DBG> EVALUATE/ADDRESS/HEX TOTAL 
0000020E 

This command determines the value of the address expression TOTAL and 
displays the result in hexadecimal radix. 
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EVALUATE / ADDRESS 


0 DBG> EVALUATE/ADDRESS/HEX A,B.C 
000004A4 
000004AC 
000004A0 


This command determines the values of the address expressions A, B, and C 
and displays these values in hexadecimal radix. 
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EXAMINE 

Displays the current value of a variable. 

FORMAT 

EXAM 1 N E [address-expression[:address-expression]] 

I---] 


PARAMETERS address-expression 

Specifies an entity to be examined. This is typically a variable name. 



including the name of an aggregate (array or record). More generally, an 
address expression may be composed of numbers and symbols, as well as one 
or more operators, operands, or delimiters. 

If a range of entities is to be examined, the value of the address expression 
that denotes the first entity in the range must be less than the value of the 
address expression that denotes the last entity in the range. 

QUALIFIERS 

/ASCIC 

Interprets each examined entity as a counted ASCII string with a 1-byte count 
field. This is an ASCII string preceded by a 1-byte count field that gives the 
length of the string to be displayed. /AC is also accepted. 

/ASCID 

Interprets each examined entity as the address of a string descriptor pointing 
to an ASCII string. The CLASS and DTYPE fields of the descriptor are not 
checked, but the LENGTH and POINTER fields provide the character length 
and address of the ASCII string. The string is then displayed. /AD is also 
accepted. 

/ASCII.n 

Interprets and displays each examined entity as an ASCII string of length n 
bytes (n characters). If n is omitted, the debugger attempts to determine a 
length from the type of the address expression. 

/ASCIW 

Interprets each examined entity as a counted ASCII string with a 1-word 
count field. This is an ASCII string preceded by a 2-byte count field that 
gives the length of the string to be displayed. /AW is also accepted. 

/ASCIZ 

Interprets and displays each examined entity as a zero-terminated ASCII 
string. This is an ASCII string followed by a zero byte, to indicate the end of 
the string. /AZ is also accepted. 

/BINARY 

Displays each examined entity as a binary integer. 
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/BYTE 

Displays each examined entity in the byte integer type (length 1 byte). 

/CONDITION-VALUE 

Interprets each examined entity (usually register RO in this case) as a 
condition-value return status and displays the message associated with 
that return status. 

/D—FLOAT 

Displays each examined entity in the D_floating type (length 8 bytes). Values 
of type D_floating may range from .29*10~ 38 to 2.7*20 38 with approximately 
16 decimal digits precision. 

/DATE-TIME 

Interprets each examined entity as a quadword integer (64 bits) containing 
the internal VAX/VMS representation of date-time. Displays the value in the 
format dd-mmm-yyyy hh:mm:ss.xx. 

/DECIMAL 

Displays each examined entity as a decimal integer. 

/DEFAULT 

Displays each examined entity in the default radix. 

/FLOAT 

Displays each examined entity in the F_floating type (length 4 bytes). Values 
of type F_floating may range from .29*10~ 38 to 1.7+10 38 with approximately 7 
decimal digits precision. 

/G-FLOAT 

Displays each examined entity in the G—floating type (length 8 bytes). Values 
of type G_floating may range from .56*20" 308 to .9*l(fi 08 with approximately 
15 decimal digits precision. 

/H—FLOAT 

Displays each examined entity in the H_floating type (length 16 bytes). 
Values of type H_floating may range from . 84*10 ~ 4932 to .59*10 4932 with 
approximately 33 decimal digits precision. 

/HEXADECIMAL 

Displays each examined entity as a hexadecimal integer. 

/INSTRUCTION 

Displays each examined entity as a VAX assembly-language instruction 
(variable length). 

/[NOJLINE 

Controls whether code locations are displayed in terms of line numbers 
(%LINE x) or in terms of routine + byte-offset. By default (/LINE), the 
debugger symbolizes code locations in terms of line numbers. 
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/LONGWORD 

Displays each examined 

/OCTAL 

Displays each examined 

/OCTAWORD 

Displays each examined 


entity in the longword integer type (length 4 bytes), 
entity as an octal integer. 

entity in the octaword integer type (length 16 bytes). 


/ PACKED:n 

Interprets each examined entity as a "packed" decimal number of length n 
nibbles. 

/PSL 

Displays each examined entity in PSL (processor status longword) format. 

/PSW 

Displays each examined entity in PSW (processor status word) format. /PSW 
is like /PSL except that only the low order word (16 bits) is displayed. 

/QUADWORD 

Displays each examined entity in the quadword integer type (length 8 bytes). 


/SOURCE 

Displays the source line corresponding to the location of each examined 
entity. 

/[NO]S YMBOL 

Controls whether symbolization occurs. By default (/SYMBOL), the debugger 
symbolizes all addresses, if possible; that is, it converts numeric addresses 
into their symbolic representation. If you specify /NOSYMBOL, the debugger 
suppresses symbolization. You can use /NOSYMBOL to increase the speed 
of command processing. 

/TASK 


Note: /TASK applies only to Ada programs. 

Interprets each examined entity as an Ada task object and displays the task 
value (the name or task ID) of that task object. 

/TYPE=(type-expression) 

Interprets the data type of each examined entity according to the type 
specified by type-expression. You may use this qualifier when examining 
the contents of an untyped location, such as a virtual address. 

/WORD 

Displays each examined entity in the type word integer (length 2 bytes). 


CD-59 






EXAMINE 


DESCRIPTION The EXAMINE command displays the entity at the location denoted by an 

address expression, in the type associated with that location. 

The most common use of the EXAMINE command is to obtain the current 
value of variables in your program. The debugger lets you specify the 
variable name in the same way it is specified in the program. Moreover, the 
debugger knows the compiler-generated type of a variable (whether it is an 
integer, real, string, array, record, and so on) and displays the variable's value 
accordingly. This is the default behavior of the EXAMINE command. 

In general, the EXAMINE command lets you obtain the contents of any 
program location. You can use the various qualifiers to override the default 
behavior and specify another format, data type, or radix. 

Examination of an aggregate (a composite data structure such as an array or 
a record structure) displays the entire aggregate in terms of all its individual 
components. You do not need to specify individual elements of the aggregate. 
The aggregate output of an array shows the subscript and value of each array 
element. Similarly, the aggregate output of a record shows the name and 
value of each record component. 

You can examine array slices by specifying a range of subscripts (use colons 
to separate the lower and upper bounds). 

The EXAMINE command sets the current entity built-in symbols %CURLOC 
and period (.) to the location denoted by the address expression specified. 
Logical predecessors (%PREVLOC and circumflex (")) and successors 
(%NEXTLOC and pressing the RETURN key) are based on the value of 
the current entity symbol. 

Related Commands: DEPOSIT, EVALUATE, (SET, SHOW, CANCEL) RADIX, 
(SET, SHOW) TYPE, CANCEL TYPE/OVERRIDE. 


EXAMPLES 

Q DBG> EXAMINE COUNT 

SUB2XC0UNT: 27 

This command displays the value of the integer variable COUNT, in module 
SUB2. 

Q DBG> EXAMINE PART.NUMBER 

INVENTORY\PART_NUMBER: "LP-3592.6-84" 

This command displays the value of the string variable PART-NUMBER. 

E DBG> EXAMINE SUB1\ARR3 
SUB1XARR3 

(1.1) : 27.01000 

(1.2) : 31.01000 

(1.3) : 12.48000 

(2.1) : 15.08000 

(2.2) : 22.30000 

(2.3) : 18.73000 

This command displays the value of all elements in array ARR3, in module 
SUB1. ARR3 is a 2 by 3 element array of real numbers. 
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Q DBG> EXAMINE SUB1\ARR3(2.1:3) 

SUB1\ARR3 

(2.1) : 15.08000 

(2.2) : 22.30000 

(2.3) : 18.73000 

This command displays the value of the elements in a slice of array 
SUB1\ARR3. The slice includes "columns" 1 through 3 of "row" 2. 

B DBG> EXAMINE VALVES.INTAKE.STATUS 
M0NIT0RWALVES . INTAKE. STATUS: OFF 

This command displays the value of the nested record component 
VALVES.INTAKE.STATUS in module MONITOR. 

B DBG> EXAMINE/SOURCE SWAP 
MAIN\SWAP 

47: procedure SWAP(X,Y: in out INTEGER) is 

This command displays the source line on which routine SWAP is declared 
(the location of routine SWAP). 

Q DBG> EXAMINE/ASC W0RK+20 
DETAT\W0RK+2O: "abed" 

This command displays the value of the entity in location WORK+20 as an 
ASCII string (abed). 

B DBG> EXAMINE/INST MAIN+2 

MAIN\MAIN+02: MOVAL L~MAINA,R11 

This command displays the instruction MOVAL from the location MAIN+2. 

B DBG> examine/nosym workdata 

0000086F: 03020100 

This command displays the value of the address WORKDATA (0000086F) as 
a virtual memory address (03020100). 

EE dbg> examine/hex fidblk 

FDEX1$MAIN\FIDBLK 


(1): 

00000008 

(2): 

00000100 

(3): 

000000AB 


This command displays the value of the array variable FIDBLK in 
hexadecimal radix. 

ED DBG> EXAMINE/DECIMAL/WORD NEWDATA:NEWDATA+6 
SUB2XNEWDATA: 256 

SUB2\NEWDATA+2: 770 

SUB2\NEWDATA+4: 1284 

SUB2XNEWDATA+6: 1798 

This command displays, in decimal radix, the values of word integer entities 
(2-byte entities) that are in the range of locations denoted by NEWDATA 
through NEWDATA + 6 bytes. 

EE dbg> examine/task alpha 

SAMPLE.ALPHA: ‘/.TASK 2 

This command interprets ALPHA to be the address of an Ada task object and 
displays the task value %TASK 2 associated with that task object. 
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EXIT 

Ends the debugging session, or ends the execution of commands in 
a command procedure or DO clause. 

FORMAT 

EXIT 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

When you issue the EXIT command at the terminal, you cause orderly 
termination of the debugging session: your program's exit handlers (if any) 
are run, the debugger exit handler is executed (closing log files, restoring the 
screen and keypad states, and so on), exit status information is displayed, and 
control is returned to the command interpreter. You cannot then continue to 
debug your program by issuing the DCL commands DEBUG or CONTINUE. 
To restart the debugger, you must run the program again. 

Note that, since EXIT runs your exit handlers, you can set breakpoints in your 
exit handlers and they will be activated upon typing EXIT. EXIT can thus be 
used to debug your exit handlers. 

If you want to terminate your debugging session without running your exit 
handlers, use the QUIT command instead of EXIT. 

When the debugger executes an EXIT command in a command procedure, 
control returns to the command stream that invoked the command procedure. 
A command stream can be the terminal, an outer (containing) command 
procedure, a DO clause in a SET BREAK, SET TRACE, or SET WATCH 
command, or a DO clause in a screen display definition. For example, if the 
command procedure was invoked from within a DO clause, control returns 
to that DO clause, where the debugger executes the next command (if any 
remain in the command sequence). 

When the debugger executes an EXIT command in a DO clause, it ignores 
any remaining commands in that clause and displays its prompt. 

Related commands: CTRL/Z, QUIT, CTRL/Y, CTRL/C, @file-spec. 


EXAMPLE 


DBG> EXIT 

$ 

This command ends the debugging session and returns you to the DCL 
command level. 
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EXITLOOP 


Exits an enclosing FOR, REPEAT, or WHILE loop. 


FORMAT 

EXITLOOP [n] 

PARAMETERS 

n 

An integer that specifies the number of levels of nested loops to exit from. 
The default is 1. 

QUALIFIERS 

None. 

DESCRIPTION 

Use the EXITLOOP command to exit an enclosing FOR, REPEAT, or WHILE 
loop. 

Related commands: FOR, REPEAT, WHILE. 


EXAMPLE 


DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN EXITLOOP) 

The WHILE 1 command generates an endless loop that executes a STEP 
command with each iteration. After each STEP, the value of X is tested. If X 
is greater than 3, the EXITLOOP command terminates the loop. 
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EXPAND 

Expands or contracts the window associated with a screen display. 

FORMAT 

EXPAND [disp-name[, ... 77 


PARAMETERS disp-name 

Specifies a display to be expanded or contracted. You may specify any of the 



following: 

• A predefined display: SRC, OUT, PROMPT, INST, REG 

• A display previously created with the SET DISPLAY command 

• A pseudo-display name: %CURDISP, %CURSCROLL, %NEXTDISP, 
%NEXTINST, % NEXT OUTPUT, %NEXTSCROLL, %NEXTSOURCE 

If you do not specify a display, the current scrolling display, as established by 
the SELECT command, is chosen. 

QUALIFIERS 

You must specify at least one qualifier. 

/DOWI\l[:n] 

Moves the bottom border of the display down by n lines (if n is positive) or 
up by n lines (if n is negative). If n is omitted, the border is moved down by 

1 line. 

/LEFT[:n] 

Moves the left border of the display to the left by n lines (if n is positive) or 
to the right by n lines (if n is negative). If n is omitted, the border is moved 
to the left by 1 line. 

/RIGHT[:n] 

Moves the right border of the display to the right by n lines (if n is positive) 
or to the left by n lines (if n is negative). If n is omitted, the border is moved 
to the right by 1 line. 

/UP[:n] 

Moves the top border of the display up by n lines (if n is positive) or down 
by n lines (if n is negative). If n is omitted, the border is moved up by 1 line. 

DESCRIPTION 

The EXPAND command moves one or more display-window borders 
according to the qualifiers specified (/UP:[n], /DOWN:[n], RIGHT:[n], 
/LEFT:[n]). 

The EXPAND command does not affect the order of a display on the display 
pasteboard. Depending on the relative order of displays, the EXPAND 
command may cause the specified display to hide or uncover another display 
or be hidden by another display, partially or totally. 
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Except for the PROMPT display, any display can be contracted to the point 
where it disappears (at which point it is marked as "removed"). It can then 
be expanded from that point. Contracting a display to the point where it 
disappears will cause it to lose any attributes that were selected for it. The 
PROMPT display cannot be contracted or expanded horizontally but can be 
contracted vertically to a height of 2 lines. 

A window border can be expanded only up to the edge of the screen. The 
left and top window borders cannot be expanded beyond the left and top 
edges of the display, respectively. The right border can be expanded up to 
255 columns from the left display edge. The bottom border of a source or 
instruction display can be expanded down only to the bottom edge of the 
display (to the end of the source module or routine's instructions). A register 
display cannot be expanded beyond its full size. 

See Appendix B for keypad-key definitions associated with the EXPAND 
command. 

Related commands: MOVE, DISPLAY, SELECT/SCROLL, (SET, SHOW) 
TERMINAL. 


EXAMPLES 

□ DBG> EXPAND/RIGHT:6 

The EXPAND command moves the right border of the current scrolling 
display to the right by 6 columns. 

S DBG> EXPAND/UP/RIGHT:-12 0UT2 

The EXPAND command moves the top border of display OUT2 up by 1 line, 
and the right border to the left by 12 columns. 

0 DBG> EXPAND/DOWN:99 SRC 

The EXPAND command moves the bottom border of display SRC down to 
the bottom edge of the screen. 
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EXTRACT 



Saves the contents of screen displays in a file or creates a file with 
all of the debugger commands necessary to re-create the current 
screen state at a later time. 

FORMAT 

EXTRACT [disp-name[, . . . ]] [file-spec] 


PARAMETERS disp-name 

Specifies a display to be extracted. You can use the wildcard character (») in 



a display name. When using /ALL, do not specify a display name. 

file-spec 

Specifies the file to which the information will be written. You can specify a 
logical name. 

If you specify /SCREEN—LAYOUT, the default specification for the file 
is SYS$DISK:[ JDBGSCREEN.COM. Otherwise, the default specification is 
SYS$DISK:[ JDEBUG.TXT. 

QUALIFIERS 

/ALL 

Extracts all displays. If /ALL is used, do not specify a display name. Do not 
specify /SCREEN-LAYOUT with /ALL. 

/APPEND 

Appends the information at the end of the file, rather than creating a new file. 
By default, a new file is created. Do not specify /SCREEN—LAYOUT with 
/APPEND. 

/SCREEN-LAYOUT 

Writes a file that contains the debugger commands describing the current 
state of the screen. This information includes the screen height and width, 
and the position, display kind, and display attributes of every existing display. 
This file can then be executed with the @file-spec command to reconstruct 
the screen at a later time. 

DESCRIPTION 

When you use the EXTRACT command to save the contents of a display into 
a file, only those lines that are currently stored in the display's memory buffer 
(as determined by the /SIZE qualifier on the DISPLAY or SET DISPLAY 
command) are written to the file. 

You cannot extract the PROMPT display into a file. 

Related commands: SAVE, DISPLAY. 
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EXAMPLES 

Q DBG> EXTRACT SRC 

This command writes all the lines in display SRC into file 
SYS$DISK:[ JDEBUG.TXT. 

Q DBG> EXTRACT/APPEND OUT [JONES.WORK]MYFILE 

This command appends all the lines in display OUT to the end of file 
[JONES.WORKJMYFILE.TXT. 

B DBG> E1XTRACT/SCREEN .LAYOUT 

This command writes the debugger commands needed to reconstruct the 
screen into file SYS$DISK:[]DBGSCREEN.COM. 
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FOR 

Executes a sequence of commands repetitively a specified number 
of times. 

FORMAT 

FOR name=expression 7 TO expression2 [ BY 
expression3 ] DO (commandf; . . . ]) 


PARAMETERS name 

Specifies the name of a count variable. 



expression 1 

Specifies an integer or enumeration type value. The expression1 and 
expression2 parameters must always be of the same type. 

expression2 

Specifies an integer or enumeration type value. The expressionl and 
expression2 parameters must always be of the same type. 

expression3 

Specifies an integer. 

command 

Specifies a debugger command. If you specify more than one command, they 
must be separated by semicolons. 

QUALIFIERS 

None. 

DESCRIPTION 

The behavior of the FOR command depends on the value of the expressions 
parameter. If expressions is positive, name is incremented from the value of 
expressionl by the value of expressions until it is greater than the value of 
expression. 

If expressions is negative, name is decremented from the value of expressionl 
by the value of expressions until it is less than the value of expression. 

If expressions is zero, the debugger returns an error message. 

If expressions is left out entirely, the debugger assumes it to have the 
value +1. 

Related commands: REPEAT, WHILE, EXITLOOP. 
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EXAMPLES 

Q DBG> FOR I = 10 TO 1 BY -1 DO (EXAMINE A(I)) 

This example examines an array backwards. 

2 DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0) 

This example initializes an array to zero. 
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GO 

Starts or resumes program execution. 

FORMAT 

GO [address-expression] 


PARAMETERS address-expression 



Specifies that program execution resume at the location denoted by the 
address expression. If you do not specify an address expression, execution 
resumes at the point of suspension or, in the case of debugger start up, at the 
transfer address. 

QUALIFIERS 

None. 

DESCRIPTION 

Note that specifying an address expression with the GO command can 
produce unexpected results because it alters the normal control flow of your 
program. For example, static storage may not be initialized, and so on. 

Related commands: STEP, SET STEP, SET BREAK, SET TRACE, SET 
WATCH. 


EXAMPLES 

Q DBG> GO 

7.DEBUG-I-EXITSTATUS, is ’‘/.SYSTEM-S-NORMAL, normal successful completion 


Q DBG> GO 

This command starts program execution, which then completes successfully. 


break at INVENTORY\RESTORE 
137: procedure RESTORE; 

This command starts program execution, which is then suspended at a 


a DBG> GO ‘/.LINE 42 

breakpoint on routine RESTORE in module INVENTORY. 


This command resumes program execution at line 42 of the currently 
executing module. 
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HELP 

Displays online help on debugger commands and selected topics. 

FORMAT 

HELP help-topic[subtopic[ ... 77 


PARAMETERS help-topic 



Specifies the name of a debugger command or topic about which you need 
help. You can specify the wildcard character (*), either singly or within a 
name. 

subtopic 

Specifies a subtopic, command qualifier, or command parameter about which 
you want further information. You can specify *, either singly or within a 
name. 

QUALIFIERS 

None . 

DESCRIPTION 

The debugger's online help facility provides the following information 
about any debugger command: a description of the command, format of 
the command, parameters that may be specified with the command, and 
qualifiers that may be specified with the command. 

To obtain information about a particular qualifier or parameter, specify it 
as a subtopic. If you want information about all command qualifiers, specify 
"qualifier" as a subtopic. If you want information about all parameters, specify 
"parameter" as a subtopic. If you want information about all parameters, 
qualifiers, and any other subtopics related to a command, specify * as a 
subtopic. 

In addition to help on commands, you can get online help on various topics 
such as screen features, keypad mode, and so on. Topic keywords are listed 
along with the commands when you type HELP. 

Type HELP Release-Notes for information about any incompatibilities 
between the current release of the debugger and previous releases. Type 
HELP New_Features for summary information on new features with this 
release of the debugger. 

For help on the keypad predefined keys, see Appendix B. 


CD-71 












HELP 


EXAMPLE 

DBG> HELP DEFINE 
DEFINE 

Defines one or more symbols and assigns them specified 
addresses for the duration of the debugging session. 

Format: 

DEFINE Bymbol=expression [,symbol=expression ... ] 

Additional information available: 

Parameters 

This command displays help for the DEFINE command. 
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IF 

Executes a sequence of commands conditionally. 

FORMAT 

IF boolean-expression THEN (commandf; ■■■])[ 
ELSE (commandf; ■..])] 


PARAMETERS boolean-expression 

Specifies a language expression that evaluates as a Boolean value (TRUE or 



FALSE) in the currently set language. 

command 

Specifies a debugger command. If you specify more than one command, you 
must separate them with semicolons. 

QUALIFIERS 

None. 

DESCRIPTION 

The IF command evaluates a boolean-expression. If the value is TRUE (as 
defined in the current language), the debugger command list in the THEN 
clause is executed. If the expression is FALSE, the command list in the ELSE 
clause is executed (if it is present). 

Related commands: FOR, REPEAT, WHILE, EXITLOOP. 


EXAMPLE 

DBG> SET BREAK R DO (IF X .LT.5 THEN (GO) ELSE (EXAMINE X)) 

This command tells the debugger to suspend program execution at location 
R (a breakpoint) and then resume program execution if the value of X is less 
than 5 (FORTRAN example). If the value of X is 5 or more, the value of X is 
displayed. 
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MOVE 


Moves a screen display vertically and/or horizontally across the 
screen. 


FORMAT MOVE [disp-name[, ... 77 


PARAMETERS disp-name 

Specifies a display to be moved. You may specify any of the following: 

• A predefined display: SRC, OUT, PROMPT, INST, REG 

• A display previously created with the SET DISPLAY command 

• A pseudo-display name: %CURDISP, %CURSCROLL, %NEXTDISP, 
%NEXTINST, %NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE 

If you do not specify a display, the current scrolling display, as established by 
the SELECT command, is chosen. 


QUALIFIERS You must specify at least one qualifier. 

/ DOWI\l[:n] 

Moves the display down by n lines (if n is positive) or up by n lines (if n is 
negative). If n is omitted, the display is moved down by 1 line. 

/LEFT[:n] 

Moves the display to the left by n lines (if n is positive) or right by n lines (if 
n is negative). If n is omitted, the display is moved to the left by 1 line. 

/R!GHT[:n] 

Moves the display to the right by n lines (if n is positive) or left by n lines (if 
n is negative). If n is omitted, the display is moved to the right by 1 line. 

/UP[:n] 

Moves the display up by n lines (if n is positive) or down by n lines (if n is 
negative). If n is omitted, the display is moved up by 1 line. 


DESCRIPTION For each display specified, the MOVE command simply creates a window 

of the same dimensions elsewhere on the screen and maps the display to it, 
while maintaining the relative position of the text within the window. 

The MOVE command does not change the order of a display on the display 
pasteboard. Depending on the relative order of displays, the MOVE 
command may cause the display to hide or uncover another display or be 
hidden by another display, partially or totally. 

A display can be moved only up to the edge of the screen. 
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See Appendix B for keypad-key definitions associated with the MOVE 
command. 

Related commands: EXPAND, DISPLAY, SELECT/SCROLL, (SET, SHOW) 
TERMINAL. 

EXAMPLES 


Q DBG> MOVE/LEFT 

The MOVE command moves the current scrolling display to the left by 1 
column. 


Q DBG> MOVE/UP:3/RIGHT:5 NEW.OUT 

The MOVE command moves display NEW_OUT up by 3 lines and to the 
right by 5 columns. 
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QUIT 

Ends the debugging session, or ends the execution of commands in 
a command procedure or DO clause (analogous to EXIT). Does not 
execute any exit handlers you have declared. 

FORMAT 

QUIT 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

When you issue the QUIT command at the terminal, you cause orderly 
termination of the debugging session: the debugger exit handler is executed 
(closing log files, restoring the screen and keypad states, and so on), exit 
status information is displayed, and control is returned to the command 
interpreter. You cannot then continue to debug your program by issuing the 
DCL commands DEBUG or CONTINUE. To restart the debugger, you must 
run the program again. 

Note that, in contrast to the EXIT command, the QUIT command does not 
execute any exit handlers that you may have declared. 

When the debugger executes a QUIT command in a command procedure, 
control returns to the command stream that invoked the command procedure. 
A command stream can be the terminal, an outer (containing) command 
procedure, a DO clause in a SET BREAK, SET TRACE, or SET WATCH 
command, or a DO clause in a screen display definition. For example, if the 
command procedure was invoked from within a DO clause, control returns 
to that DO clause, where the debugger executes the next command (if any 
remain in the command sequence). 

When the debugger executes a QUIT command in a DO clause, it ignores any 
remaining commands in that clause and displays its prompt. 

Related commands: EXIT, CTRL/Z, CTRL/Y, CTRL/C, @file-spec. 

EXAMPLE 


DBG> QUIT 

$ 

This command, when issued from the DBG> prompt, ends the debugging 
session and returns you to DCL command level. 


CD-76 













REPEAT 


REPEAT 

Executes a sequence of commands repetitively a specified number 
of times. 

FORMAT 

REPEAT lang-exp DO (command[; . . . ]) 


PARAMETERS lang-exp 

Denotes any expression in the currently set language that evaluates to a 



positive integer. 

command 

Specifies a debugger command. If you specify more than one command, they 
must be separated by semicolons. 

DESCRIPTION 

The REPEAT command is a simple form of the FOR command. The REPEAT 
command executes a sequence of commands repetitively a specified number 
of times, without providing the options for establishing count parameters that 
the FOR command does. 

Related commands: FOR, WHILE, EXITLOOP. 

EXAMPLE 


DBG> REPEAT 10 DO (STEP) 

This command causes the debugger to STEP 10 times. 
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SAVE 

Preserves the contents of an existing screen display in a new 
display. 

FORMAT 

SAVE old-disp AS new-disp [, ... 7 


PARAMETERS old-disp 

Specifies the display whose contents you want to save. 



new-disp 

Specifies the name of the new display to be created. This new display then 
receives the contents of the old-disp display. 

QUALIFIERS 

None. 

DESCRIPTION 

The SAVE command permits a "snapshot" of an existing display to be saved 
in a new display for later reference. The new display is created with the same 
text contents as the existing display. In general, the new display is given all 
the attributes or characteristics of the old display except that it is removed 
from the screen and is never automatically updated. You can later recall the 
saved display to the terminal screen with the DISPLAY command. 

When you use the SAVE command, only those lines that are currently stored 
in the display's memory buffer (as determined by the /SIZE qualifier on 
the DISPLAY or SET DISPLAY command) are stored in the saved display. 
However, in the case of a saved source or instruction display, the debugger 
also lets you see any other source lines associated with that module or any 
other instructions associated with that routine (by scrolling the saved display). 

You cannot save the PROMPT display. 

Related commands: EXTRACT, DISPLAY. 

EXAMPLE 


DBG> save REG AS OLDREG 

This command saves the contents of the display named REG into the newly 
created display named OLDREG. 
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SCROLL 

Scrolls a screen display to make other parts of the text visible 
through the display window. 

FORMAT 

SCROLL [disp-name] 


PARAMETERS disp-name 



Specifies a display to be scrolled. You may specify any of the following: 

• A predefined display: SRC, OUT, PROMPT, INST, REG 

• A display previously created with the SET DISPLAY command 

• A pseudo-display name: %CURDISP, %CURSCROLL, %NEXTDISP, 
%NEXTINST, %NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE 

If you do not specify a display, the current scrolling display, as established by 
the SELECT command, is chosen. 

QUALIFIERS 

/BOTTOM 

Scrolls down to the bottom of the display's text. 

/DOWN:[n] 

Scrolls down over the display's text by n lines to reveal text further down in 
the display. If n is omitted, the display is scrolled by approximately 3/4 of its 
window height. 

/LEFT:[n] 

Scrolls left over the display's text by n columns to reveal text beyond the left 
window border. You cannot scroll past column 1. If n is omitted, the display 
is scrolled left by 8 columns. 

/RIGHT[:n] 

Scrolls right over the display's text by n columns to reveal text beyond the 
right window border. You cannot scroll past column 255. If n is omitted, the 
display is scrolled right by 8 columns. 

/TOP 

Scrolls up to the top of the display's text. 

/UP[:n] 

Scrolls up over the display's text by n lines to reveal text further up in the 
display. If n is omitted, the display is scrolled by approximately 3/4 of its 
window height. 
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DESCRIPTION The SCROLL command moves a display up, down, right, or left relative to its 

window so that various parts of the display text can be made visible through 
the window. 

Use the SELECT/SCROLL command to select the target display for the 
SCROLL command (the current scrolling display). 

See Appendix B for keypad-key definitions associated with the SCROLL 
command. 

Related commands: SELECT. 


EXAMPLES 


□ 

E 


dbg> scroll/left 


This command scrolls the current scrolling display to the left by 8 columns. 

DBG> SCROLL/UP:4 ALPHA 

This command scrolls display ALPHA 4 lines up. 
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SEARCH 

Searches the source code for a specified string and displays source 
lines that contain an occurrence of the string. 

FORMAT 

SEARCH [range] [string] 


PARAMETERS range 

Specifies a program region to be searched. Use any of the following formats: 


mod-name Searches the specified module from line 0 

to the end of the module. 

mod-name\line-num Searches the specified module from the 

specified line number to the end of the 
module. 

Searches the specified module from the line 
number specified on the left of the colon to 
the line number specified on the right. 

Searches the module designated by the 
current scope setting, from the specified 
line number to the end of the module. 

Searches the module designated by the 
current scope setting from the line number 
specified on the left of the colon to the line 
number specified on the right. 

Searches the same module as that from 
which a source line was most recently 
displayed (as a result of a TYPE, EXAMINE 
/SOURCE, or SEARCH command, for 
example), beginning at the first line 
following the line most recently displayed 
and continuing to the end of the module. 


mod-name\line-num:line-num 


line-num 


line-num:line-num 


null (no entry) 


string 

Specifies the source code characters for which to search. If you do not specify 
a string, the string specified in the last SEARCH command, if any, is used. 

You must enclose the string in quotation marks or apostrophes if 

• The string has any leading or trailing space or tab characters 

• The string contains an embedded semicolon 

• The range parameter is null 

If the string is enclosed in quotation marks, use a double quotation mark 
("") to indicate an enclosed quotation mark. If the string is enclosed in 
apostrophes, use a double apostrophe (") to indicate an enclosed apostrophe. 
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QUALIFIERS /ALL 

Specifies that the debugger search for all occurrences of the string in the 
specified range and display every line containing an occurrence of the string. 

/IDENTIFIER 

Specifies that the debugger search for an occurrence of the string in the 
specified range but display the string only if it is not bounded on either side 
by a character that can be part of an identifier in the current language. 

/NEXT 

Specifies that the debugger search for the first occurrence of the string in the 
specified range and display only the line containing this occurrence. This is 
the default. 

/STRING 

Specifies that the debugger search for and display the string as specified, and 
not interpret the context surrounding an occurrence of the string, as it does in 
the case of /IDENTIFIER. This is the default. 


DESCRIPTION SEARCH command qualifiers determine whether the debugger: (1) searches 

for all occurrences (/ALL) of the string or only the next occurrence (/NEXT); 
and (2) displays any occurrence of the string (/STRING) or only those 
occurrences in which the string is not bounded on either side by a character 
that can be part of an identifier in the current language (/IDENTIFIER). 

Note that a module in which a search is to take place must be set. Use the 
SHOW MODULE command to determine whether a particular module is set. 
Then use the SET MODULE command, if necessary. 

If you plan to issue several SEARCH commands with the same qualifier, you 
can first use the SET SEARCH command to establish a new default qualifier 
(for example, SET SEARCH ALL makes the SEARCH command behave like 
SEARCH/ALL). Then you do not have to use that qualifier with the SEARCH 
command. You can override the current default qualifiers for the duration of 
a single SEARCH command by specifying other qualifiers. 

Related commands: (SET, SHOW) SEARCH, (SET, SHOW) LANGUAGE, 
(SET, SHOW) SCOPE, (SET, SHOW) MODULE. 


EXAMPLES 

Q DBG> SEARCH/STRING/ALL 40:50 D 
module C0B0LTEST 


40: 

02 

D2N 

COMP-2 

VALUE 

-234560000000. 

41: 

02 

D 

COMP-2 

VALUE 

222222.33. 

42: 

02 

DN 

COMP-2 

VALUE 

-222222.333333. 

47: 

02 

DR0 

COMP-2 

VALUE 

0.1. 

48: 

02 

DR5 

COMP-2 

VALUE 

0.000001. 

49: 

02 

DR10 

COMP-2 

VALUE 

0.00000000001. 

50: 

02 

DR15 

COMP-2 

VALUE 

0.0000000000000001 


This command searches for all occurrences of the letter D in lines 40 through 
50 of the module COBOLTEST. 
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Q DBG> SEARCH/IDENTIFIER/ALL 40:50 D 
module COBOLTEST 

41: 02 D COMP-2 VALUE 222222.33. 


This command searches for all occurrences of the letter D in lines 40 through 
50 of the module COBOLTEST. The debugger displays the only line where 
the letter D (the search string) is not bounded on either side by a character 
that can be part of an identifier in the current language. 

S DBG> SEARCH/NEXT 40:50 D 
module COBOLTEST 

40: 02 D2N COMP-2 VALUE -234560000000. 


This command searches for the next occurrence of the letter D in lines 40 to 
50 of the module COBOLTEST. 


Q DBG> SEARCH/NEXT 
module COBOLTEST 

41: 02 D COMP-2 VALUE 222222.33. 


This command searches for the next occurrence of the letter D. The debugger 
assumes D to be the search string because D was the last one entered and no 
other search string was specified. 
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SELECT 

Selects a screen display as the current error, input, instruction, 
output, program, prompt, scrolling, or source display. 

FORMAT 

SELECT [disp-name] 


PARAMETERS disp-name 

Specifies the display to be selected. You may specify any one of the 



following, with the restrictions noted in the qualifier descriptions: 

• A predefined display (SRC, OUT, INST, REG, and PROMPT). 

• A display previously created with the SET DISPLAY command 

• A pseudo-display name: %CURDISP, %CURSCROLL, %NEXTDISP, 
%NEXTINST, %NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE 

If you omit this parameter and do not specify a qualifier, you "unselect" 
the current scrolling display (no display then has the scrolling attribute). If 
you omit this parameter but specify a qualifier (/INPUT, /SOURCE, and 
so on), you unselect the current display with that attribute (see the qualifier 
descriptions). 

QUALIFIERS 

/ERROR 

If you specify a display, selects it as the current error display. This causes all 
debugger diagnostic messages to go to that display. The display specified 
must be either an output display or the PROMPT display. 

If you do not specify a display, the PROMPT display is selected as the current 
error display. 

By default, the PROMPT display has the error attribute. 

/INPUT 

If you specify a display, selects it as the current input display. This causes 
that display to echo debugger input (which always appears in the PROMPT 
display). The display specified must be an output display. 

If you do not specify a display, the current input display is unselected and 
debugger input is not echoed to any display (debugger input appears only in 
the PROMPT display). 

By default, no display has the input attribute. 

/INSTRUCTION 

If you specify a display, selects it as the current instruction display. This 
causes the output of all EXAMINE/INSTRUCTION commands to go to that 
display. The display specified must be an instruction display. 

If you do not specify a display, the current instruction display is unselected 
and no display has the instruction attribute. 
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By default, for all languages except MACRO, no display has the instruction 
attribute. If the language is set to MACRO, the INST display has the 
instruction attribute by default. 

/OUTPUT 

If you specify a display, selects it as the current output display. This causes 
debugger output that is not already directed to another display to go to 
that display. The display specified must be either an output display or the 
PROMPT display. 

If you do not specify a display, the PROMPT display is selected as the current 
output display. 

By default, the OUT display has the output attribute. 

/PROGRAM 

If you specify a display, selects it as the current program display. This causes 
the debugger to try to force program input and output to that display. 
Currently, only the PROMPT display may be specified. 

If you do not specify a display, the current program display is unselected and 
program input and output are no longer forced to the specified display. 

By default, the PROMPT display has the program attribute, except on 
Micro VAX workstations, where the program attribute is unselected. 

/PROMPT 

Selects the specified display as the current prompt display. This is where the 
debugger prompts for input. Currently, only the PROMPT display may be 
specified. Moreover, you cannot unselect the PROMPT display (the PROMPT 
display always has the prompt attribute). 

/SCROLL 

If you specify a display, selects it as the current scrolling display. This is the 
default display for the SCROLL, MOVE, and EXPAND commands. Although 
any display may have the scroll attribute, note that you can use only the 
MOVE and EXPAND commands (not the SCROLL command) with the 
PROMPT display. 

If you do not specify a display, the current scrolling display is unselected and 
no display has the scroll attribute. 

By default, for all languages except MACRO, the SRC display has the scroll 
attribute. If the language is set to MACRO, the INST display has the scroll 
attribute by default. 

Note: If no qualifier is specified, /SCROLL is assumed by default. 

/SOURCE 

If you specify a display, selects it as the current source display. This causes the 
output of all TYPE and EXAMINE/SOURCE commands to go to that display. 
The display specified must be a source display. 

If you do not specify a display, the current source display is unselected and 
no display has the source attribute. 

By default, for all languages except MACRO, the SRC display has the source 
attribute. If the language is set to MACRO, no display has the source attribute 
by default. 
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DESCRIPTION Attributes are used to select the current scrolling display and to direct various 

types of debugger output to particular displays. This gives you the option 
of mixing or isolating different types of information, such as debugger input, 
output, diagnostic messages, and so on in scrollable displays. 

You use the SELECT command with one or more qualifiers (/ERROR, 
/SOURCE, and so on) to assign one or more corresponding attributes to a 
display. If you do not specify a qualifier, the /SCROLL qualifier is assumed 
by default. 

If you use the SELECT command without specifying a display name, in 
general the attribute assignment indicated by the command qualifier is 
canceled ("unselected"). To reassign display attributes you must use another 
SELECT command. See the individual qualifier descriptions for details. 

See Appendix B for keypad-key definitions associated with the SELECT 
command. 

Related commands: SHOW SELECT, SCROLL, MOVE, EXPAND, DISPLAY, 
SET DISPLAY. 


EXAMPLES 

□ DBG> SELECT/SOURCE/SCROLL SRC2 

The SELECT/SOURCE/SCROLL command selects display SRC2 as the 
current source and scrolling display. 

0 DBG> SELECT/INPUT/ERROR OUT 

The SELECT/INPUT/ERROR command selects display OUT as the current 
input and error display. This causes debugger input, debugger output 
(assuming OUT is the current output display), and debugger diagnostic 
messages to be logged in the OUT display in the correct sequence. 


E DBG> SELECT/SOURCE 


The SELECT/SOURCE command unselects (removes the source attribute 
from) the currently selected source display. The output of a TYPE or 
EXAMINE/SOURCE command will then go to the currently selected output 
display. 
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SET ATSIGN 


Establishes the default file specification that the debugger uses 
when searching for command procedures. 

FORMAT 

SET ATSIGN file-spec 

PARAMETERS file-spec 

Specifies any part of a VAX/VMS file specification (for example, a directory 
name or a file type) that the debugger is to use by default when searching 
for a command procedure. If you do not supply a full file specification, the 
debugger assumes SYS$DISK:[]DEBUG.COM as the default file specification 
for any missing field. 


You may specify a logical name that translates to a search list. In this case, 
the debugger processes the file specifications in the order they appear in the 
search list until the command procedure is found. 

QUALIFIERS 

None. 

DESCRIPTION 

When you invoke a command procedure during a debugging 
session, the debugger, by default, assumes that its file specification is 
SYS$DISK:[ ]DEBUG.COM. The SET ATSIGN command lets you override 
this default. 


Related commands: @file-spec, SHOW ATSIGN. 


EXAMPLES 


□ DBG> SET ATSIGN USER:[JONES.DEBUG].DBG 
DBG> (DTEST 


When you invoke @TEST, the debugger looks for the file TEST.DBG in 
USER:[JONES.DEBUG]. 
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SET BREAK 


Establishes a breakpoint at the location denoted by an address- 
expression, or at instructions of a particular class. 


FORMAT SET BREAK [addr-expr[, . . . ]][WHEN (cond-expr)] 

[DO (command[; ...])] 


PARAMETERS addr-expr 

Specifies an address expression (a program location) at which a breakpoint 
is to be set. In general, this may be a line number, a routine name, a label, 
or a location in memory. However, the /MODIFY and /RETURN qualifiers 
are used with specific kinds of address expressions. Do not use the wildcard 
character (*). Do not use an address expression when specifying /BRANCH, 
/CALL, /EXCEPTION, /INSTRUCTION[=(opcode-list)], /INTO, /[NO]JSB, 
/LINE, /OVER, /[NO]SHARE, or /[NO]SYSTEM. 

command 

Specifies a debugger command that is to be executed as part of the DO clause 
when break action is taken. 

cond-expr 

Specifies a conditional expression in the currently set language that is to be 
evaluated every time the breakpoint occurs. If the expression is TRUE, break 
action occurs, and the debugger reports that a break has occurred. If the 
expression is FALSE, break action does not occur. In this case, a report is 
not issued, the commands specified by the DO clause are not executed, and 
program execution is continued. 


QUALIFIERS /AFTER:n 

Specifies that break action not be taken until the nth time the designated 
breakpoint is encountered (n is a decimal integer). Thereafter, the breakpoint 
occurs every time it is encountered provided that conditions in the WHEN 
clause are TRUE. The command SET BREAK/AFTER:1 has the same effect as 
the SET BREAK command. 

/BRANCH 

Causes the debugger to break on every branch instruction encountered 
(including BEQL, BGTR, BLEQ, BGEQ, BLSS, BGTRU, BLEQU, BVC, BVS, 
BGEQU, BLSSU, BRB, BRW, JMP, BBS, BBC, BBSS, BBCS, BBSC, BBCC, 
BBSSI, BBCCI, BLBS, BLBC, ACBB, ACBW, ACBL, ACBF, ACBD, ACBG, 
ACBH, AOBLEQ, AOBLSS, SOBGEQ, SOBGTR, CASEB, CASEW, CASEL) 
during execution. Do not specify an address expression with this qualifier. 
See also /INTO, /OVER. 
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/CALL 

Causes the debugger to break on every call instruction (including the CALLS, 
CALLG, BSBW, BSBB, JSB, RSB, and RET instructions) encountered during 
execution. Do not specify an address expression with this qualifier. See also 
/INTO, /OVER. 

/EVENT=event-name 


Note: /EVENT applies only to Ada and SCAN. See the VAX Ada and VAX 
SCAN documentation for complete information. 

Causes the debugger to break every time the specified event occurs (if that 
event is defined and detected by the run-time system). If you specify an 
address expression with /EVENT, causes the debugger to break every time 
the specified event occurs for that address expression. Event names depend 
on the run-time facility and are identified in Appendix E for Ada and SCAN. 
Note that you cannot specify an address expression with certain event names. 

/EXCEPTION 

Causes the debugger to break every time an exception is signaled. The break 
action occurs before any user-written exception handlers are invoked. SET 
BREAK/EXCEPTION is the same as SET EXCEPTION BREAK. Do not specify 
an address expression with this qualifier. 

/INSTRUCTION 

Causes the debugger to break on every instruction executed. Do not specify 
an address expression with this qualifier. See also /INTO, /OVER. 

/INSTRUCTION=(opcode[, . . . ]) 

Causes the debugger to break on every instruction whose opcode is in the 
list. Do not specify an address expression with this qualifier. See also /INTO, 
/OVER. 

/INTO 

Sets breakpoints within called routines (as well as within the main program) 
when /BRANCH, /CALL, /INSTRUCTION=[(opcode-list)], or /LINE is 
specified; that is, when an address expression is not explicitly specified. 
/INTO is the default behavior and is the opposite of /OVER. When 
using /INTO, you can further qualify the breakpoints with the /[NO]JSB, 
/[NO]SHARE, and /[NO]SYSTEM qualifiers. 

/[NO]JSB 

Qualifies /INTO. Use /[NO]JSB with /INTO and one of these qualifiers: 
/BRANCH, /CALL, /INSTRUCTION[=(opcode-list)], or /LINE. /JSB is 
the default for all languages except DIBOL. /JSB lets the debugger break 
within routines that are called by the JSB or CALL instruction. /NOJSB 
(the DIBOL default) specifies that breakpoints not be set within routines 
called by JSB instructions. In DIBOL, user-written routines are called by the 
CALL instruction and DIBOL run-time library routines are called by the JSB 
instruction. Do not specify an address expression with this qualifier. 

/LINE 

Causes the debugger to break at the start of each new line. Do not specify an 
address expression with this qualifier. See also /INTO, /OVER. 
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/MODIFY 

Causes a break at every instruction that writes to and modifies the value of 
the location indicated by the address expression. The address expression is 
typically a variable name. 

The SET BREAK/MODIFY command acts exactly like a SET WATCH 
command and operates under the same restrictions. 

If you specify an absolute address for the address expression, the debugger 
may not be able to associate the address with a particular data object. In 
this case, the debugger uses a default length of 4 bytes. You can change this 
length, however, by setting the type to either WORD (which changes the 
default length to 2 bytes) or BYTE (which changes the default length to 1 
byte). 

/OVER 

Sets breakpoints only within the main program (not within called routines) 
when /BRANCH, /CALL, /INSTRUCTION=[(opcode-list)], or /LINE is 
specified; that is, when an address expression is not explicitly specified. 
/OVER is the opposite of /INTO. 

/RETURN 

Sets a breakpoint on the RETURN (RET) instruction from an indicated 
routine. This qualifier can only be applied to routines called with a CALLS or 
CALLG instruction; it cannot be used with JSB routines. Breaking on the RET 
instruction also allows you to inspect the local environment before the RET 
instruction removes the routine's call frame from the call stack. 

For this qualifier, the address-expression parameter is an instruction address 
within a CALLS or CALLG routine. It may simply be a routine name, in 
which case it specifies the routine start address. However, you can also 
specify another location in a routine, so you can see only those returns that 
are taken after a certain code path is followed. 

/[NOJSHARE 

Qualifies /INTO. Use /[NOJSHARE with /INTO and one of these qualifiers: 
BRANCH, /CALL, /INSTRUCTION[=(opcode-list)J, or /LINE. /SHARE 
(default) lets the debugger break within shareable image routines as well 
as other routines. /NOSHARE specifies that breakpoints not be set within 
shareable images. Do not specify an address expression with this qualifier. 

/[NOJSILENT 

Controls whether or not the "break ..." message (and source code) is 
displayed when break action is taken. /NOSILENT (default) specifies that the 
message be displayed. /SILENT specifies that no message or source code be 
displayed. /SILENT overrides /SOURCE. 

/[NOJSOURCE 

Controls whether or not the source code is displayed when break action 
is taken. /SOURCE (default) specifies that the source code be displayed. 
/NOSOURCE specifies that no source code be displayed. /SILENT overrides 
/SOURCE. 
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/[,NOJSYSTEM 

Qualifies /INTO. Use /[NOJSYSTEM with /INTO and one of these qualifiers: 
/BRANCH, /CALL, /INSTRUCTION[=(opcode-list)], or /LINE. /SYSTEM 
(default) lets the debugger break within system routines (PI space) as well 
as other routines. /NOSYSTEM specifies that breakpoints not be set within 
system routines. Do not specify an address expression with this qualifier. 

/TEMPORARY 

Causes the breakpoint to disappear after it is activated (the breakpoint does 
not remain permanently set). 


DESCRIPTION When a breakpoint is activated, the debugger takes the following action: 

1 Suspends program execution at the breakpoint location. 

2 Evaluates the expression in a WHEN clause, if one was specified when 
the breakpoint was set. If the value of the expression is FALSE, execution 
continues and the debugger does not perform the next three steps. 

3 Displays the location of the breakpoint. Also, displays the line of source 
code corresponding to that instruction if the SOURCE parameter is in 
effect by virtue of a previous SET STEP SOURCE command. 

4 Executes the commands in a DO clause, if one was specified when the 
breakpoint was set. If the DO clause contains a GO command, execution 
continues and the debugger does not perform the next step. 

5 Issues the DBG> prompt. 

The following qualifiers affect what output is seen when a breakpoint is 
reached: 

/[NO]SILENT 

/[NO]SOURCE 

The following qualifiers affect the timing and duration of breakpoints: 

/AFTER:n 

/TEMPORARY 

Breakpoints may be set on classes of instructions or events by using one of 
the following qualifiers: 

/BRANCH 

/CALL 

/EVENT=event-name 

/EXCEPTION 

/INSTRUCTION 

/INSTRUCTION=(opcode-list) 

/LINE 

/RETURN 

The following qualifiers affect what happens at a routine call: 

/INTO 

/[NO]JSB 

/OVER 

/[NO]SHARE 
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/[NO]SYSTEM 

The /MODIFY qualifier is used to monitor changes at program locations 
(typically changes in the values of variables). 

Related commands: (SHOW, CANCEL) BREAK, CANCEL ALL, SET TRACE, 
SET WATCH, GO, STEP, (SET, SHOW) EVENT-FACILITY. 


EXAMPLES 

Q DBG> SET BREAK SWAPV/.LINE 12 

This command sets a breakpoint on line 12 of module SWAP. 

Q DBG> SET BREAK/AFTER:3 SUB2 

This command sets a breakpoint that will trigger on the third and subsequent 
times that SUB2 (a routine) is executed. 

B DBG> SET BREAK L00P1 DO (EXAMINE D; STEP; EXAMINE Y; GO) 

This command sets a breakpoint at location LOOP1. When the breakpoint is 
reached, the following commands are executed: 

EXAMINE D 
STEP 

EXAMINE Y 
GO 


Q DBG> SET BREAK/TEMPORARY 1440 
dbg> SHOW break 

breakpoint at 1440 [temporary] 

This command sets a temporary breakpoint at location 1440. After that 
breakpoint is activated, it disappears. 
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SET DEFINE 



Establishes a default qualifier (/ADDRESS, /COMMAND, or /VALUE) 
for the DEFINE command. 

FORMAT 

S ET D E F1N E define-default 


PARAMETERS define-default 

Specifies the default to be established for the DEFINE command. Valid 



keywords (which correspond to DEFINE command qualifiers) are the 
following: 

ADDRESS Subsequent DEFINE commands will be treated as DEFINE 

/ADDRESS. This is the default. 

COMMAND Subsequent DEFINE commands will be treated as DEFINE 

/COMMAND. 

VALUE Subsequent DEFINE commands will be treated as DEFINE/VALUE. 

QUALIFIERS 

None. 

DESCRIPTION 

The SET DEFINE command establishes a default qualifier for subsequent 
DEFINE commands. The parameters that you specify in the SET DEFINE 
command have the same names as the DEFINE command qualifiers. DEFINE 
command qualifiers determine whether the DEFINE command binds a symbol 
to an address, a command string, or a value. 

You can override the current DEFINE default for the duration of a single 
DEFINE command by specifying another qualifier. Use the SFIOW DEFINE 
command to identify the current DEFINE defaults. 

Related commands: SHOW DEFINE, DEFINE, DELETE, SHOW SYMBOL 
/DEFINED. 

EXAMPLE 


dbg> set define value 

The SET DEFINE VALUE command specifies that subsequent DEFINE 
commands are to be treated as DEFINE/VALUE. 
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SET DISPLAY 


Creates a new screen display. 


FORMAT SET DISPLAY disp-name [ AT wspec][dkind] 

[<■■■] 


PARAMETERS disp-name 

Specifies the name of the display you are defining. If a display by the same 
name already exists, you must cancel the first display before you can define 
the new display. 

You may specify more than one display, each with an optional window 
specification (wspec) and display kind (dkind). 

wspec 

Specifies the screen window at which the display is to be positioned. You 
may specify any of the following: 

• A predefined window. For example, RH1 (right top half). See 
Appendix C. 

• A window definition previously established with the SET WINDOW 
command. 

• A window specification of the form (start-line, line-count [,start-column, 
column-count]). The specification can include expressions which may 
be based on the built-in symbols %PAGE and % WIDTH (for example, 

% WIDTH/4). 

If you omit the wspec parameter, the display is positioned at window HI 
or H2 by default, alternating between HI and H2 with each SET DISPLAY 
command. 

dkind 

Specifies the display kind. Valid keywords are the following: 

DO (cmd-list) Specifies an automatically updated output display. 

The commands in cmd-list are executed each 
time the debugger gains control. Their output 
forms the contents of the display. 

INSTRUCTION Specifies an instruction display. If selected as 

the current instruction display with the SELECT 
/INSTRUCTION command, it will display the 
output from subsequent EXAMINE/INSTRUCTION 
commands. 
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QUALIFIERS 


INSTRUCTION (command) Specifies an automatically updated instruction 

display. The command specified must be 
an EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 

OUTPUT Specifies an output display. If selected as the 

current output display with the SELECT/OUTPUT 
command, it will display any debugger output 
that is not directed to another display. If selected 
as the current input display with the SELECT 
/INPUT command, it will echo debugger input. 

If selected as the current error display with 
the SELECT/ERROR command, it will display 
debugger diagnostic messages. 

REGISTER Specifies an automatically updated register 

display. The display is updated each time the 
debugger gains control. 

SOURCE Specifies a source display. If selected as 

the current source display with the SELECT 
/SOURCE command, it will display the output 
from subsequent TYPE or EXAMINE/SOURCE 
commands. 

SOURCE (command) Specifies an automatically updated source display. 

The command specified must be a TYPE or 
EXAMINE/SOURCE command. The source 
display is updated each time the debugger gains 
control. 


If you omit the dkind parameter, an OUTPUT display is created. 


/[NOJDYNAMIC 

Controls whether a display automatically adjusts its window dimensions in 
proportion when a SET TERMINAL command is issued. By default 
(/DYNAMIC) all newly created displays adjust their window dimensions 
automatically, except for register displays. A register display maintains its 
window dimensions when the screen height or width are changed. 

/HIDE 

Places a newly created display at the bottom of the display pasteboard. This 
hides the new display behind any previously existing displays that share the 
same region of the screen. 

/HIDE has the same effect as /PUSH. 

/MARK-CHANGE 

Marks the lines that change in a DO(cmd-list) display each time the display 
is automatically updated. Any lines in which the contents have changed 
since the last time the display was updated are highlighted with reverse 
video. This qualifier is particularly useful when you want any variables in an 
automatically updated display to be highlighted when they change. 

This qualifier is not applicable to other kinds of displays. 


CD-95 






SET DISPLAY 


/POP 

Places a newly created display at the top of the display pasteboard, ahead of 
any other displays except the PROMPT display. The new display then hides 
any other displays that share the same region of the screen, except for the 
PROMPT display. This is the default action of the SET DISPLAY command. 

/PUSH 

Has the same effect as /HIDE. 

/REMOVE 

Specifies that the display not be shown on the screen unless you explicitly 
request it with the DISPLAY command. The display is then marked as being 
removed from the display pasteboard, although it still exists. 

/SIZE:n 

Sets the maximum size of a display to be n lines. If more than n lines are 
written to the display, the oldest lines are lost as new lines are added. If 
you omit this qualifier, the default size is 64 lines, except for the predefined 
display OUT (100 lines). 

For an output or DO display, /SIZE:n specifies that the display should 
hold the n most recent lines of output. For a source or instruction display, 
n gives the number of source lines or lines of instructions that can be 
placed in the memory buffer at any one time. However, you can scroll a 
source display over the entire source code of the module whose code is 
displayed (source lines are paged into the buffer as needed). Similarly, you 
can scroll an instruction display over all of the instructions of the routine 
whose instructions are displayed (instructions are decoded from the image as 
needed). 


DESCRIPTION The SET DISPLAY command is used to create a new display. The command 

lets you specify the name, window, and display kind. By default, an output 
display is created, and it is placed on top of the display pasteboard, ahead of 
any existing displays but behind the PROMPT display. You can also hide a 
newly created display at the bottom of the pasteboard, so it will not conceal 
existing displays. And you can create a new "removed" display. 

Related commands: (SHOW, CANCEL) DISPLAY, DISPLAY, (SET, SHOW, 
CANCEL) WINDOW, SELECT, (SET, SHOW) TERMINAL. 


EXAMPLES 

Q DBG> SET DISPLAY DISP2 AT RS45 
DBG> SELECT/OUTPUT DISP2 

The SET DISPLAY command creates a new display named DISP2 essentially 
at the right bottom half of the screen, above the PROMPT display, which is 
located at S6. This is an output display by default. The SELECT/OUTPUT 
command then selects DISP2 as the current output display. 
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Q DBG> SET WINDOW TOP AT (1,8,45,30) 

DBG> SET DISPLAY NEWINST AT TOP INSTRUCTION 
DBG> SELECT/INST NEWINST 

The SET WINDOW command creates a window named TOP starting at line 
1 and column 45, and extending down for 8 lines and to the right for 30 
columns. The SET DISPLAY command creates an instruction display named 
NEWINST to be displayed through TOP. The SELECT/INST command 
selects NEWINST as the current instruction display. 
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SET EDITOR 


Establishes the editor that will be invoked by the EDIT command. 


FORMAT SET EDITOR [command-line] 


PARAMETERS command-line 

Specifies a command line to invoke a particular editor on your system when 
you use the EDIT command. 

You must specify a command line unless you use the /CALLABLE _EDT, 
/CALLABLE—LSEDIT, or /CALLABLE_TPU qualifiers. If you do not use 
one of these qualifiers, the editor specified in the SET EDITOR command line 
is spawned to a subprocess when you issue the EDIT command. 

You may specify a command line with the /CALLABLE—LSEDIT and 
/CALLABLE_TPU qualifiers, but not with the /CALLABLE_EDT qualifier. 


QUALIFIERS /CALLABLE-EDT 

Specifies that the callable version of the EDT editor is to be invoked 
when you use the EDIT command. Do not specify a command line with 
/CALLABLE_EDT (a command line of "EDT" is used). 

/CALLABLE—LSEDIT 

Specifies that the callable version of the VAX Language-Sensitive Editor 
(LSEDIT) is to be invoked when you use the EDIT command. If you also 
specify a command line, it is passed to callable LSEDIT. If you do not specify 
a command line, the default command line is "LSEDIT". 

/CALLABLE—TPU 

Specifies that the callable version of the VAX Text Processing Utility 
(VAXTPU) is to be invoked when you use the EDIT command. If you 
also specify a command line, it is passed to callable VAXTPU. If you do not 
specify a command line, the default command line is "EDIT/TPU". 

/[NOJSTART—POSITION 


Note: Currently, only the VAX Language-Sensitive Editor (specified either as 
LSEDIT or /CALLABLE—LSEDIT) supports this qualifier. 

Controls whether the /START-POSITION qualifier is appended to the 
specified or default command line when the EDIT command is used. 

This qualifier affects the initial position of the editor's cursor. By default, 
(/NOSTART—POSITION), the editor's cursor is placed at the start of source 
line 1, regardless of which line is centered in debugger's source display 
or whether a line number is specified in the EDIT command. If /START- 
POSITION is specified, the cursor is placed either on the line whose number 
is specified in the EDIT command, or (if no line number is specified) on the 
line that is centered in the current source display. 
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DESCRIPTION The SET EDITOR command may be used to specify any editor that is installed 

on your system. In general, the command line specified as parameter to the 
SET EDITOR command is spawned and executed in a subprocess. However, 
if you use EDT, LSEDIT, or VAXTPU, you have the option of invoking these 
editors in a more efficient way. You can specify the /CALLABLE _EDT, 
/CALLABLE—LSEDIT, or /CALLABLE _TPU qualifiers, which cause the 
callable versions of EDT, LSEDIT, and VAXTPU, respectively, to be invoked 
by the EDIT command. In the case of LSEDIT and VAXTPU, you may also 
specify a command line that will be executed by the callable editor. 

Related commands: SHOW EDITOR, EDIT, (SET, SHOW, CANCEL) 
SOURCE. 


EXAMPLES 


□ 


DBG> SET EDITOR ’QMAIL$EDIT 


The SET EDITOR command causes the EDIT command to spawn the 
command line '@MAIL$EDIT which invokes the same editor as you 
use in MAIL. 


s 


a 


DBG> SET EDITOR/CALLABLE.TPU 

The SET EDITOR command causes the EDIT command to invoke callable 
VAXTPU with the default command line of EDIT/TPU. 


DBG> SET EDITOR/CALLABLE_TPU EDIT/TPU/SECTION=MYSECINI.TPU$SECTION 



a 


The SET EDITOR command causes the EDIT command to 
invoke callable VAXTPU with the command line EDIT/TPU 
/SECTION=MYSECINI.TPU$SECTION. 

DBG> SET EDITOR/CALLABLE_LSEDIT/START_POSITION 

The SET EDITOR command causes the EDIT command to invoke callable 
LSEDIT with the default command line of LSEDIT. Also the /START- 
POSITION qualifier will be appended to the command line, so that the 
editing session will start on the source line that is centered in the debugger's 
current source display. 
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SET EVENT-FACILITY 

Establishes the run-time library facility for eventpoints that are set 
with the SET BREAK/EVENT and SET TRACE/EVENT commands. 

Note: The SET EVENT-FACILITY command currently applies only to Ada and 



SCAN. See the VAX Ada and VAX SCAN documentation for complete 
information. 

FORMAT 

SET EVENT-FACILITY facility-name 


PARAMETERS facility-name 

Specifies a run-time library facility for eventpoints. Valid keywords are the 



following: 

ADA Enables recognition of Ada-specific events when you use the (SET, 

CANCEL) BREAK/EVENT and (SET, CANCEL) TRACE/EVENT commands. 
Valid Ada event names are identified in Appendix E. 

SCAN Enables recognition of SCAN-specific events when you use the (SET, 

CANCEL) BREAK/EVENT and (SET, CANCEL) TRACE/EVENT commands. 
Valid SCAN event names are identified in Appendix E. 

QUALIFIERS 

None. 

DESCRIPTION 

The Ada event facility lets you set breakpoints and tracepoints on tasking 
events and exception events. The SCAN event facility lets you set breakpoints 
and tracepoints on pattern-matching events. 

Use the SHOW EVENT-FACILITY command to identify the events applicable 
to the currently set language. 

Related commands: SHOW EVENT-FACILITY, (SET, CANCEL) BREAK 
/EVENT, SHOW BREAK, (SET, CANCEL) TRACE/EVENT, SHOW TRACE. 


EXAMPLES 

Q DBG> SET EVENT-FACILITY ADA 

This command establishes Ada as the current run-time library facility. 
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SET EXCEPTION BREAK 


Causes the debugger to treat any exception condition generated by 
your program as a breakpoint. 


FORMAT SET EXCEPTION BREAK 


PARAMETERS None. 


QUALIFIERS None. 


DESCRIPTION The SET EXCEPTION BREAK command has the same effect as the SET 

BREAK/EXCEPTION command. 

As a result of this command, whenever your program generates an 
exception condition, the debugger suspends program execution, reports 
the exception condition, and prompts you for input. Thus, whenever an 
exception breakpoint is activated, you have the opportunity to issue debugger 
commands. When you want to continue program execution, you can issue 
one of the following GO commands: 

• A GO command without an address-expression parameter. In this case, 
the debugger fields and resignals the exception, thus allowing any user- 
declared exception handlers to execute. 

• A GO command with an address-expression parameter. In this case, the 
debugger allows program execution to continue at the specified location, 
thus inhibiting the execution of any user-declared exception handlers. 

Note that you cannot issue a STEP or CALL command to continue program 
execution after an exception breakpoint is activated. The debugger issues 
a warning message because the STEP or CALL command is illegal in this 
context. 

Related commands: CANCEL EXCEPTION BREAK, (SET, CANCEL) BREAK 
/EXCEPTION. 


EXAMPLE 


DBG> SET EXCEPTION BREAK 


This command tells the debugger to treat an exception condition as a 
breakpoint. This allows you to issue debugger commands when your program 
generates an exception condition. 
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SET IMAGE 


Loads the run-time symbol table (RST) for one or more shareable 
images and establishes the current image. 


FORMAT SET IMAGE [image-name[, ... 77 


PARAMETERS image-name 

Specifies a shareable image that is to be "set" (that is, loaded into the RST). 
Do not use the wildcard character (*). When using /ALL, do not specify an 
image name. 


QUALIFIERS /ALL 

Specifies that all shareable images are to be set. When using /ALL, do not 
specify an image. 


DESCRIPTION The "current" image is the current debugging context: a SHOW MODULE 

command identifies the modules of the current image. If only one image is 
specified with the SET IMAGE command, that image becomes the current 
image. If a list of images is specified, the last one in the list becomes the 
current image. If /ALL is specified, the current image is unchanged. 

Before an image can be set with the SET IMAGE command, it must have been 
linked with the /DEBUG or /TRACE qualifier on the LINK command. If an 
image was linked /NOTRACE, no symbol information is available for that 
image and you cannot specify it with the SET IMAGE command. 

Note that when you use the SET IMAGE command to establish a new 
current image, all definitions created with the DEFINE/ADDRESS and 
DEFINE/VALUE commands are deleted (definitions created with the DEFINE 
/COMMAND and DEFINE/KEY commands are retained, however). 

Related commands: (SHOW, CANCEL) IMAGE, (SET, SHOW, CANCEL) 
MODULE. 


EXAMPLES 

Q DBG> SET IMAGE SHARE1 
DBG> SET MODULE SUBR 
DBG> SET BREAK SUBR 


This sequence of commands shows how to set a breakpoint on routine SUBR 
in module SUBR of shareable image SHARE 1. The SET IMAGE command 
sets the debugging context to SHARE 1. The SET MODULE command loads 
the symbol records of module SUBR into the RST. The SET BREAK command 
sets a breakpoint on routine SUBR. 
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SET KEY 

Establishes the current key state. 

FORMAT 

SET KEY 


PARAMETERS None. 


QUALIFIERS 

/[l\IO]LOG 

Controls whether a message is displayed indicating that the key state has 
been set. /LOG (default) displays the message. 

/[NO]STATE[=state-name] 

Specifies a key state to be established as the current state. You may specify 
a predefined key state, such as GOLD, or a user-defined state. A state name 
can be any appropriate alphanumeric string. /NOSTATE (default) leaves the 
current state unchanged. 

DESCRIPTION 

Keypad mode must be enabled (SET MODE KEYPAD) before you can use 
this command. Keypad mode is enabled by default. 

By default, the current key state is the "DEFAULT" state. When you define 
function keys using the DEFINE/KEY command, you can use the /IF_STATE 
qualifier of that command to assign a specific state name to the key definition. 
If that state is not set when you press the key, the definition will not be 
processed. The SET KEY/STATE command lets you change the current state 
to the appropriate state. 

You can also change the current state by pressing a key that causes a state 
change (a key that was defined with the DEFINE/KEY/LOCK_STATE/SET_ 
STATE qualifier combination). 

Related commands: DEFINE/KEY, DELETE/KEY, SHOW KEY. 


EXAMPLE 


DBG> SET KEY/STATE=PR0G3 

The SET KEY command changes the key state to the PROG3 state. You can 
now use the key definitions that are associated with this state. 
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SET LANGUAGE 



Establishes the current language. 

FORMAT 

SET LANGUAGE language-name 


PARAMETERS language-name 

Specifies a language. Valid keywords are the following: ADA, BASIC, BLISS, 



C, COBOL, DIBOL, FORTRAN, MACRO, PASCAL, PLI, RPG, SCAN, and 
UNKNOWN. 

QUALIFIERS 

None. 

DESCRIPTION 

At debugger start up, the debugger sets the current language to that in which 
the module containing the transfer address (the main program) is written. If 
you want to debug a module written in a different source language from that 
of the main program, you can change the language with the SET LANGUAGE 
command. 

The current language influences several debugger default parameters, namely, 
those of type, radix, and step values. In addition, languages differ on such 
matters as type conversions; the evaluation of expressions; and acceptable 
syntax, special characters, and symbols. 

The SET LANGUAGE UNKNOWN command may be used when debugging 
a program that is written in an unsupported language. To maximize the 
useability of the debugger with unsupported languages, the SET LANGUAGE 
UNKNOWN command allows the debugger to accept data formats that match 
those of any supported language. 

Related commands: SHOW LANGUAGE, SET TYPE, SET RADIX, SET 
MODE. 


EXAMPLES 

Q DBG> SET LANG COBOL 

This command establishes COBOL as the current language. 

g DBG> SET LANG PASCAL 

This command establishes PASCAL as the current language. 
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SET LOG 

Specifies a log file to which the debugger writes after a SET 
OUTPUT LOG command has been issued. 

FORMAT 

SET LOG file-spec 


PARAMETERS file-spec 

Denotes the file specification of the log file. If you do not supply a full file 



specification, the debugger assumes SYS$DISK:[]DEBUG.LOG as the default 
file specification for any missing field. 

If you specify a version number and that version of the file already exists, 
the debugger writes to the file specified, appending the log of the debugging 
session onto the end of that file. 

QUALIFIERS 

None. 

DESCRIPTION 

Note that the SET LOG command only determines the name of a log file; it 
does not cause the debugger to create or write to the specified file. The SET 
OUTPUT LOG command accomplishes that. 

If you have issued a SET OUTPUT LOG command but no SET LOG 
command, the debugger writes to the file SYS$DISK:[ JDEBUG.LOG by 
default. 

If the debugger is writing to a log file and you specify another log file with 
the SET LOG command, the debugger closes the former file and begins 
writing to the file specified in the SET LOG command. 

Related commands: SET OUTPUT LOG, SET OUTPUT SCREEN-LOG. 

EXAMPLES 


□ DBG> SET LOG CALC 

DBG> SET OUTPUT LOG 

The SET LOG command specifies the debugger log file to be 

SYS$DISK:[ JCALC.LOG. The SET OUTPUT command causes your input 


and debugger output to be logged to that file. 

Q DBG> SET LOG "[CODEPROJ]FEB29.TMP" 

DBG> SET OUTPUT LOG 

The SET LOG command specifies the debugger log file to be 
[CODEPROJ]FEB29.TMP. The SET OUTPUT command causes your input 
and debugger output to be logged to that file. 
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SET MARGINS 


Specifies the leftmost source-line character position at which 
to begin display of a source line and/or the rightmost character 
position at which to end display of a source line. 


FORMAT 


SET MARGINS 


rm 

lm:rm 

Im: 

:rm 


PARAMETERS Im 

The source-line character position at which to begin display of the line of 
source code (the left margin). 

rm 

The source-line character position at which to end display of the line of 
source code (the right margin). 


QUALIFIERS None. 


DESCRIPTION By default, the debugger displays a source line beginning at character position 

1 of the source line. This is actually character position 9 on your terminal 
screen. The first eight character positions on the screen are reserved for the 
line number and cannot be manipulated by the SET MARGINS command. 

If you specify a single number, the debugger sets the left margin to 1 and the 
right margin to the number specified. 

If you specify two numbers, separated with a colon, the debugger sets the 
left margin to the number on the left of the colon and the right margin to the 
number on the right. 

If you specify a single number followed by a colon, the debugger sets the left 
margin to that number and leaves the right margin unchanged. 

If you specify a colon followed by a single number, the debugger sets the 
right margin to that number and leaves the left margin unchanged. 

Increasing the left margin setting is useful when the source code is deeply 
indented. Decreasing the right margin setting (from its default value of 255) 
prevents the wrapping of long lines by truncating them. 

The SET MARGINS command affects only the display of source lines, that is, 
the display resulting from commands such as TYPE and EXAMINE/SOURCE. 
The SET MARGINS command does not affect the display resulting from 
commands (such as EXAMINE, EVALUATE, SHOW MODE, and so on) that 
do not display source code. If a command displays source code together with 
other information—as, for example, STEP/SOURCE does—the display 
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of source code is affected by the current margin settings but the other 
information is not. 

Related commands: SHOW MARGINS. 


EXAMPLES 


Q DBG> SHOW MARGINS 

left margin: 1 , right margin: 255 
DBG> TYPE 14 
module FORARRAY 

14: DIMENSION IARRAY(4:5,5), VECTOR(10), I3D(3,3,4) 


This example displays the default margin settings for a line of source code (1 
and 255). 


Q DBG> SET MARGINS 39 
DBG> SHOW MARGINS 
left margin: 1 . right margin: 39 
DBG> TYPE 14 
module FORARRAY 

14: DIMENSION IARRAY(4:5,5), VECTOR 


This example shows how the display of a line of source code changes when 
you change the right margin setting from 255 to 39. 

g DBG> SET MARGINS 10:45 
DBG> SHOW MARGINS 
left margin: 10 , right margin: 45 
DBG> TYPE 14 
module FORARRAY 

14: IMENSION IARRAY(4:5,5), VECTOR(10), 


This example shows the display of the same line of source code after both 
margins are changed. 


Q DBG> SET MARGINS :100 
DBG> SHOW MARGINS 

left margin: 10 , right margin: 100 

This example shows how to change the right margin setting while retaining 
the previous left margin setting. 

g DBG> SET MARGINS 5: 

DBG> SHOW MARGINS 

left margin: 5 , right margin: 100 

This example shows how to change the left margin setting while retaining the 
previous right margin setting. 
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SET MAX_SOURCE-FILES 



Specifies the maximum number of source files that the debugger 
may keep open at any one time. 

FORMAT 

SET MAX_SOURCE_FILES n 


PARAMETERS n 

Specifies the maximum number of source files that the debugger may keep 



open at any one time. The value of n may not exceed 20. The default value 
is 5. 

QUALIFIERS 

None. 

DESCRIPTION 

By default, the debugger may keep five source files open at any one time. 

Opening a source file requires the use of an I/O channel, which is a limited 
system resource. Both the program and the debugger use I/O channels. To 
ensure that the debugger does not use all available I/O channels and thus 
cause the program to fail (for lack of an available I/O channel), you can issue 
the SET MAX—SOURCE—FILES command to specify the maximum number 
of source files (and thus source file I/O channels) that the debugger may use 
at any one time. 

Note that the value of MAX—SOURCE—FILES does not limit the number 
of source files that the debugger can open; rather, it limits the number that 
may be kept open at any one time. Thus, if the debugger reaches this limit, it 
must close a file in order to open another one. 

Note too that setting MAX—SOURCE—FILES to a very small number can 
make the debugger's use of source files inefficient. 

Related commands: SHOW MAX-SOURCE-FILES, (SET, SHOW, CANCEL) 
SOURCE. 


EXAMPLE 

DBG> SHOW MAX.SOURCE.FILES 
max_Bourco_files: 5 
DBG> SET MAX.SOURCE.FILES 8 
DBG> SHOW MAX_SOURCE_FILES 

max.source.liles: 8 

The SET MAX—SOURCE—FILES 8 command enables the debugger to keep a 
maximum of eight files open at any one time. 
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SET MODE 


Enables or disables a debugger mode. 


FORMAT SET MODE mode[, . . . ] 


PARAMETERS mode 

Specifies a debugger mode to be enabled or disabled. Valid keywords are the 
following: 


DYNAMIC 


NODYNAMIC 


G—FLOAT 


NOG_FLOAT 


KEYPAD 


NOKEYPAD 


LINE 


Enables dynamic module setting. In dynamic module setting, 
the debugger sets certain modules automatically during 
program execution so that you do not have to issue the 
SET MODULE command for these modules. Whenever 
the debugger prompt is displayed (whenever the debugger 
interrupts execution), the debugger automatically sets the 
module enclosing the PC location and issues an informational 
message. If the module is already set, dynamic module 
setting has no effect. SET MODE DYNAMIC is the default. 

Disables dynamic module setting. This may be desirable if 
performance becomes a problem as more and more modules 
are set. When dynamic module setting is disabled, you must 
set modules yourself with the SET MODULE command. 

Specifies that the debugger interpret double-precision 
floating-point constants entered in expressions as G_FLOAT 
(does not affect the interpretation of variables declared 
in your program). EXAMINE/D—FLOAT and DEPOSIT/D— 
FLOAT may be used to override SET MODE G_FLOAT for 
the duration of an EXAMINE or DEPOSIT command. 

Specifies that the debugger interpret double-precision 
floating-point constants entered in expressions as D_FLOAT 
(does not affect the interpretation of variables declared 
in your program). EXAMINE/G—FLOAT and DEPOSIT/G- 
FLOAT may be used to override SET MODE NOG_FLOAT 
for the duration of an EXAMINE or DEPOSIT command. SET 
MODE NOG_FLOAT is the default. 

Enables keypad mode. When keypad mode is enabled, 
you can use the keys on the numeric keypad to perform 
certain predefined functions. Several debugger commands, 
especially useful in screen mode, are bound to the keypad 
keys (see Appendix B). You can also redefine the key 
functions with the DEFINE/KEY command. SET MODE 
KEYPAD is the default. 

Disables keypad mode. When keypad mode is disabled, 
the keys on the numeric keypad do not have predefined 
functions, nor can you assign debugger functions to those 
keys with the DEFINE/KEY command. 

Specifies that the debugger display code locations in terms 
of line numbers, if possible. SET MODE LINE is the default. 
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NOLINE 

SCREEN 


NOSCREEN 

SCROLL 


NOSCROLL 


SYMBOLIC 


NOSYMBOLIC 


Specifies that the debugger display code locations in terms 
of routine + byte-offset rather than in terms of line numbers. 

Enables screen mode. When screen mode is enabled, you 
can divide the terminal screen into rectangular regions, so 
different data can be displayed in different regions. Screen 
mode lets you view more information more conveniently 
than the default, line-oriented, noscreen mode. You can use 
the predefined displays, or you can define your own. 

Disables screen mode. SET MODE NOSCREEN is the default. 

Enables scroll mode. When scroll mode is enabled, a screen¬ 
mode output or DO display is updated by scrolling the output 
line by line, as it is generated. SET MODE SCROLL is the 
default. 

Disables scroll mode. When scroll mode is disabled, a 
screen-mode output or DO display is updated only once per 
command, instead of line by line as it is generated. Disabling 
scroll mode reduces the amount of screen updating that 
takes place and may be useful with slow terminals. 

Enables symbolic mode. When symbolic mode is enabled, 
the debugger displays the locations denoted by address 
expressions symbolically (if possible) and displays instruction 
operands symbolically (if possible). EXAMINE/NOSYMBOLIC 
may be used to override SET MODE SYMBOLIC for the 
duration of an EXAMINE command. SET MODE SYMBOLIC 
is the default. 

Disables symbolic mode. When symbolic mode is disabled, 
the debugger does not attempt to symbolize numeric 
addresses (it does not cause the debugger to convert names 
to numbers). This may speed up command processing. 
Numeric addresses are displayed in decimal radix by default. 
The SET RADIX command may be used to specify a different 
radix. EXAMINE/SYMBOLIC may be used to override SET 
MODE NOSYMBOLIC for the duration of an EXAMINE 
command. 


QUALIFIERS 

None. 

DESCRIPTION 

The default values of these modes are the same for all languages. 

Related commands: (SHOW, CANCEL) MODE, EXAMINE, DEPOSIT, (SET, 
SHOW, CANCEL) RADIX. 

EXAMPLE 

DBG> SET MODE SCREEN 

This command puts the debugger in screen mode. 
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SET MODULE 


Loads the symbol records of a module into the debugger's run-time 
symbol table (RST). 


FORMAT SET MODULE [ module-name [, . . . ]] 


PARAMETERS module-name 

Specifies a module whose symbol records are to be loaded into the RST. 
Do not use the wildcard character (*). When using /ALL, do not specify a 
module name. 


QUALIFIERS /ALL 

Specifies that the symbol records of all modules in the current image be 
loaded into the RST. When using /ALL, do not specify a module name. 

/ALLOCATE 

Note: Since memory is allocated automatically during dynamic module setting, 
you need to use /ALLOCATE only when dynamic module setting is 
disabled (SET MODE NODYNAMIC). 

Expands the debugger memory pool. The debugger will then expand its 
memory pool by some increment of PO space each time its internal memory 
pool is exhausted. The debugger allocates additional memory by calling 
$EXPREG. If your program also allocates memory dynamically, the location 
of the allocated memory may be affected. In this case, you may want to avoid 
the /ALLOCATE qualifier. 

/[NO]RELATED 

Note: /[NOJRELATED applies only to Ada programs. 

Controls whether the debugger loads into the RST the symbol records of a 
module that is related to a specified module through a with-clause or subunit 
relationship. 

SET MODULE/RELATED (default) loads symbol records for related modules 
as well as for those specified. This makes names declared in related modules 
visible so you can reference them in debugger commands as you could 
reference them within the Ada source code. SET MODULE/NORELATED 
loads symbol records only for modules that are specified (no symbol records 
are loaded for related modules). 
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DESCRIPTION 

Note: The (SET, SHOW, CANCEL) MODULE commands operate on modules in 
the current image. This is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 

Symbol records must be present in the RST if the debugger is to recognize 
and properly interpret the symbols declared in your program. The process 
by which the symbol records of a module are loaded into the RST is called 
setting a module. 

At debugger start up, the debugger sets the module containing the transfer 
address (the main program). By default, dynamic module setting is enabled 
(SET MODE DYNAMIC). Therefore, the debugger sets modules automatically 
as the program executes so that you can reference symbols as you need them. 
Specifically, whenever execution is suspended, the debugger sets the module 
containing the currently executing routine. In the case of Ada programs, as a 
module is set dynamically, its related modules are also set automatically, by 
default, to make the appropriate symbols accessible (visible). 

Dynamic module setting makes accessible most of the symbols you might 
need to reference. If you need to reference a symbol in an arbitrary module 
that is not already set, use the SET MODULE command. 

If dynamic module setting is disabled (SET MODE NODYNAMIC), only the 
module containing the transfer address is set for you. You need to set other 
modules yourself with the SET MODULE command. 

When dynamic module setting is enabled, memory is allocated automatically 
to accommodate the increasing size of the RST. If dynamic module setting 
is disabled, the debugger may not let you set more modules unless you 
either allocate more memory (with the ALLOCATE or SET MODULE 
/ALLOCATE command) or reduce the number of set modules (with the 
CANCEL MODULE command). Whether dynamic module setting is enabled 
or disabled, if performance becomes a problem as more modules are set, use 
the CANCEL MODULE command to reduce the number of set modules. 

If a parameter in the SET SCOPE command designates a program location in 
a module that is not already set, the SET SCOPE command sets that module. 

Related commands: (SHOW, CANCEL) MODULE, SET MODE 
[NOjDYNAMIC, (SET, SHOW, CANCEL) IMAGE, ALLOCATE. 


EXAMPLES 

Q DBG> SET MODULE SUB1 


This command sets module SUB1 (loads the symbol records of module SUB1 
into the RST). 


2 DBG> SET MODULE/ALL 

y.DEBUG-W-NOFREE, no free storage available 
DBG> SET MODULE/ALL/ALLOCATE 

The SET MODULE/ALL command attempts to set all of the modules in the 
current image. The debugger responds that there is not sufficient memory. 
The SET MODULE/ALL/ALLOC ATE expands the memory pool as needed 
to accommodate all of the modules. 
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0 DBG> SET IMAGE SHARE3 
DBG> SET MODULE MATH 
DBG> SET BREAK %LINE 31 

The SET IMAGE command makes shareable image SHARE3 the current 
image. The SET MODULE command sets module MATH in image SHARE3. 
The SET BREAK command sets a breakpoint on line 31 of module MATH. 
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SET OUTPUT 



Enables or disables a debugger output option. 

FORMAT 

SET OUTPUT output-optionf, ... 7 

PARAMETERS output-option 

Specifies an output option to be enabled or disabled. Valid keywords are the 
following: 


LOG 

Specifies that debugger input and output be recorded in a 
log file. If you specify the log file by the SET LOG command, 
the debugger writes to that file; otherwise, by default the 
debugger writes to SYS$DISK[ ]:DEBUG.LOG. 


NOLOG 

Specifies that debugger input and output not be recorded in 
a log file. NOLOG is the default. 


SCREEN-LOG 

Specifies that, while in screen mode, the screen contents be 
recorded in a log file as the screen is updated. To log the 
screen contents you must also specify SET OUTPUT LOG. 
See the description of the LOG option regarding specifying 
the log file. 


NOSCREEN-LOG 

Specifies that the screen contents, while in screen mode, 
not be recorded in a log file. NOSCREEN—LOG is the default. 


TERMINAL 

Specifies that debugger output be displayed at the terminal. 
TERMINAL is the default. 


NOTERMINAL 

Specifies that debugger output, except for diagnostic 
messages, not be displayed at the terminal. 


VERIFY 

Specifies that the debugger echo, on the current output 
device, each input command string that it is executing from 
a command procedure or DO clause. The current output 
device is by default SYS$OUTPUT, the terminal, but may be 
redefined with the logical name DBGSOUTPUT. 


NOVERIFY 

Specifies that the debugger not display each input command 
string that it is executing from a command procedure or DO 
clause. NOVERIFY is the default. 

QUALIFIERS 

None. 



DESCRIPTION Debugger output options control the way in which debugger responses to 

commands are displayed and recorded. 

Related commands: SHOW OUTPUT, (SET, SHOW) LOG, SET MODE 
SCREEN, @file-spec, (SET, SHOW) ATSIGN. 
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EXAMPLE 

DBG> SET OUTPUT VERIFY.LOG,NOTERMINAL 

This command specifies that the debugger do the following: 

• Output each command string that it is executing from a command 
procedure or DO clause. 

• Record debugger output and user input in a log file. 

• Not display output at the terminal (except for diagnostic messages). 
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SET PROMPT 


Lets you change the debugger prompt string from DBG> to a string 
of your choice. 


FORMAT SET PROMPT string 


PARAMETERS string 


Specifies the string which is to become the new prompt. If the string contains 
blanks, semicolons, or lowercase characters, you must enclose it in single or 
double quotation marks. 


QUALIFIERS None. 


EXAMPLE 


DBG> SET PROMPT " 

$ SET PROMPT "dbg: " 
d b g : SET PROMPT "DBG> 
DBG> 


n 



The successive SET PROMPT commands change the debugger prompt from 
"DBG> " to to "d b g then back to "DBG> 
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SET RADIX 



Establishes the default radix for the entry and/or display of integer 
data. When used with /OVERRIDE, causes all data to be displayed 
as integer data of the specified radix. 

FORMAT 

SET RADIX radix 


PARAMETERS radix 

Specifies the default radix to be established. Valid keywords are the 



following: 

BINARY Sets the default radix to binary. 

DECIMAL Sets the default radix to decimal. This is the default for all 

languages except BLISS and MACRO. 

DEFAULT Sets the default radix to the language default. 

OCTAL Sets the default radix to octal. 

HEXADECIMAL Sets the defaut radix to hexadecimal. This is the default for 

BLISS and MACRO. 

QUALIFIERS 

/INPUT 

Sets only the input radix to the specified radix. 

/OUTPUT 

Sets only the output radix to the specified radix. 

/OVERRIDE 

Causes all data to be displayed as integer data of the specified radix. 

DESCRIPTION 

When you use the EXAMINE, DEPOSIT, or EVALUATE commands, the 
default radix influences how integer data is interpreted and displayed. By 
default, the radix is hexadecimal for BLISS and MACRO and decimal for 
other languages. 

The SET RADIX command lets you change the default radix for the entry 
and/or display of integer data (the input radix and output radix, respectively). 
The debugger will interpret and display integer data in the new radix. 
However, other values (such as floating or enumeration type values) will 
be interpreted and displayed as they normally would be. 

The SET RADIX/OVERRIDE command causes all data (not just data that 
was originally typed as integer data) to be displayed as integer data of the 
specified radix. 

Note that the EVALUATE, EXAMINE, and DEPOSIT commands have radix 
qualifiers that let you further override, for the duration of that command, 
any default radix previously established with the SET RADIX or SET RADIX 
/OVERRIDE command. 
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SET RADIX 


Related commands: (SHOW, CANCEL) RADIX, (SET, SHOW, CANCEL) 
MODE, EVALUATE, EXAMINE, DEPOSIT. 


EXAMPLES 

□ DBG> SET RADIX HEX 


This command sets the default radix to hexadecimal. This means that, by 
default, integer data will be interpreted and displayed in hexadecimal radix. 

S DBG> SET RADIX/INPUT OCT 

This command sets the default radix for input to octal. This means that, by 
default, integer data that is entered will be interpreted in octal radix. 

0 DBG> SET RADIX/OUTPUT BIN 

This command sets the default radix for output to binary. This means that, 
by default, integer data will be displayed in binary radix. 

Q DBG> SET RADIX/OVERRIDE DECIMAL 

This command sets the override radix to decimal. This means that, by default, 
all data will be displayed as decimal integer data. 
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SET SCOPE 



Establishes how the debugger looks up symbols when a path-name 
prefix is not specified. 

FORMAT 

SET SCOPE 

location[, ... 7 

PARAMETERS location 

Denotes a program region to be used for the interpretation of symbols that do 
not have a path-name prefix. A location may be any of the following: 


path-name prefix 

Specifies the scope region denoted by the path-name 
prefix. A path-name prefix consists of the names 
of one or more nesting program elements (module, 
routine, block, and so on), with each name separated 
by a backslash character (\). When a path-name 
prefix consists of more than one name, list a nesting 
element to the left of the \ and a nested element to the 
right of the \. A common path-name prefix format is 
module\routine\block \. 



If you specify only a module name and that name is 
the same as the name of a routine, use the /MODULE 
qualifier; otherwise, the debugger assumes that you are 
specifying the routine. 


n 

Specifies the scope region denoted by the routine which 
is n levels down the call stack (n is a decimal integer). A 
scope region specified by an integer changes dynamically 
as the program executes. The value 0 denotes the routine 
that is currently executing, the value 1 denotes the caller 
of that routine, and so on down the call stack. The 
default scope is 0,1,2, . . . ,N, where N is the number of 
calls in the call stack. 


\ 

Specifies the global scope region—that is, the set of all 
program locations in which a global symbol is known. 

The definition of a global symbol and the way it is 
declared depends on the language. 


When you specify more than one location parameter, you establish a scope 
search list. If the debugger cannot interpret the symbol using the first 
parameter, it uses the next parameter, and continues using parameters in 
order of their specification until it successfully interprets the symbol or until it 
exhausts the parameters specified. 

QUALIFIERS 

/MODULE 



Indicates that the name specified is the name of a module and not of a 
routine. You need to use /MODULE only when you specify a module name 
as the scope region, and that module name is the same as the name of a 
nested routine. 
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SET SCOPE 


DESCRIPTION By default, the debugger looks up a symbol specified without a path-name 

prefix according to the scope search list 0,2,2, . . . ,N, where N is the number 
of calls in the call stack. This scope search list is based on your current PC 
and changes dynamically as your program executes. The default scope means 
that a symbol lookup such as "EXAMINE X" first looks for X in the routine 
that is currently executing (scope 0); if no X is visible there, the debugger 
looks in the caller of that routine (scope 1), and so on down the call stack; 
if X is not found in scope N, the debugger searches the rest of the run-time 
symbol table (RST), then searches the global symbol table (GST), if necessary. 

The SET SCOPE command lets you change this default symbol lookup. This 
is useful if, for example, you need to use a path name repeatedly to access 
a multiply-defined symbol. By specifying that path-name prefix in the SET 
SCOPE command, you establish a new default scope for symbol lookup. You 
can then reference the symbol without using a path-name prefix. Note that, 
when you use the SET SCOPE command, the debugger searches only the 
program locations you specify explicitly. 

If you specify a module name in a SET SCOPE command, the debugger "sets" 
that module if it is not already set. However, if all you want to do is set a 
module, it is best to use the SET MODULE command rather than disturb the 
current scope search list with the SET SCOPE command. 

If a name you specify is the name of both a module and a nested routine, 
the debugger sets the scope to the routine, unless you use the /MODULE 
qualifier to indicate that you want to set the scope to the module. 

To restore the default scope, use the CANCEL SCOPE command. 

Related commands: (SHOW, CANCEL) SCOPE, SET MODULE. 


EXAMPLES 

Q DBG> EXAMINE Y 

%DEBUG-W-NOUNIQUE, symbol ’Y’ is not unique 
DBG> SHOW SYMBOL Y 
data CHECK_IN\Y 
data INVENT0RY\C0UNT\Y 
DBG> SET SCOPE INVENT0RY\C0UNT 
DBG> EXAMINE Y 
INVENT0RY\C0UNT\Y: 347.15 

The first EXAMINE Y command indicates that symbol Y is multiply defined 
and cannot be resolved from the current scope search list. The SHOW 
SYMBOL command displays the different declarations of symbol Y. The 
SET SCOPE command tells the debugger to look for symbols without path¬ 
name prefixes in routine COUNT of module INVENTORY. The subsequent 
EXAMINE command can now interpret Y unambiguously. 

@ DBG> SET SCOPE 1 


This command tells the debugger to look for symbols without path-name 
prefixes in scope 1, which is the caller of the routine that is currently 
executing. If the debugger cannot find a symbol in scope 1, it looks no 
further. 
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SCOPE 


gj DBG> SHOW SYMBOL X 

data ALPHAXX ! global X 

data ALPHA\BETA\X ! local X 

data X (global) ! same as ALPHA\X 

DBG> SHOW SCOPE 

scope: 0 [ = ALPHA\BETA ] 

DBG> SYMBOLIZE X 
address ALPHA\BETA\7.R0: 

ALPHA\BETA\X 
DBG> SET SCOPE \ 

DBG> SYMBOLIZE X 
address 00000200: 

ALPHAXX 

address 00000200: (global) 

X 


The SHOW SYMBOL command indicates that there are two declarations 
of the symbol X—a global ALPHA\X (shown twice) and a local 
ALPHA\BETA\X. Within the current scope, the local declaration of X 
(ALPHA\BETA\X) is visible. After the scope is set to the global scope (SET 
SCOPE \), the global declaration of X is made visible. 
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SET SEARCH 



Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or 
/STRING) for the SEARCH command. 

FORMAT 

SET SEARCH search-defaultf, ... 7 

PARAMETERS 

search-default 

Specifies a default to be established for the SEARCH command. Valid 
keywords (which correspond to SEARCH command qualifiers) are the 
following: 


ALL 

Subsequent SEARCH commands will be treated as SEARCH/ALL, 
rather than SEARCH/NEXT. 


IDENTIFIER 

Subsequent SEARCH commands will be treated as SEARCH 
/IDENTIFIER, rather than SEARCH/STRING. 


NEXT 

Subsequent SEARCH commands will be treated as SEARCH 
/NEXT, rather than SEARCH/ALL. This is the default. 


STRING 

Subsequent SEARCH commands will be treated as SEARCH 
/STRING, rather than SEARCH/IDENTIFIER. This is the default. 

QUALIFIERS 

None. 



DESCRIPTION The SET SEARCH command establishes default qualifiers for subsequent 

SEARCH commands. The parameters that you specify in the SET SEARCH 
command have the same names as the SEARCH command qualifiers. 
SEARCH command qualifiers determine whether the SEARCH command: 

(1) searches for all occurrences (ALL) of a string or only the next occurrence 
(NEXT); and (2) displays any occurrence of the string (STRING) or only those 
occurrences in which the string is not bounded on either side by a character 
that can be part of an identifier in the current language (IDENTIFIER). 

You can override the current SEARCH default for the duration of a single 
SEARCH command by specifying other qualifiers. Use the SHOW SEARCH 
command to identify the current SEARCH defaults. 

Related commands: SEARCH, SHOW SEARCH, (SET, SHOW) LANGUAGE. 
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SET SEARCH 


EXAMPLE 


DBG> SHOW SEARCH 

search settings: search for next occurrence, as a string 
DBG> SET SEARCH IDENTIFIER 
DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> SET SEARCH ALL 
DBG> SHOW SEARCH 

search settings: search for all occurrences, as an identifier 

The SET SEARCH IDENTIFIER command tells the debugger to search for an 
occurrence of the string in the specified range but display the string only if it 
is not bounded on either side by a character that can be part of an identifier 
in the current language. 

The SET SEARCH ALL command tells the debugger to search for (and 
display) all occurrences of the string in the specified range. 
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SET SOURCE 



Specifies where the debugger is to search for source files. 

FORMAT 

SET SOURCE directory-spec[, ... 7 


PARAMETERS directory-spec 

Specifies any part of a VAX/VMS file specification (typically a device 



/directory) that the debugger is to use by default when searching for a 
source file. For any part of a full file specification that you do not supply, the 
debugger uses the file specification stored in the module's symbol record— 
that is, the file specification that the source file had at compile time. 

If you specify more than one directory in a single SET SOURCE command, 
separating each directory name with a comma, you create a source directory 
search list (you may also specify a search list logical name that is defined at 
your process level). The debugger handles a source directory search list by 
searching the first directory specified to locate the source file for a module, 
then the second directory specified, then the next, and so on, until it either 
locates the source file or exhausts the list of directories. 

QUALIFIERS 

/EDIT 


Note: /EDIT applies mainly to Ada programs, 



Specifies that the directory search list will be used to locate source files for 
editing when you use the EDIT command. 

/MODULE=module-name 

Specifies that the directory search list will be used to locate source files only 
for the specified module. 

DESCRIPTION 

By default, the debugger expects a source file to be in the same directory 
it was in at compile time (the debugger also checks that the creation and 
revision date and time of a source file match the information in the debugger's 
symbol table). If a source file has been moved to a different directory since 
compile time, you can use the SET SOURCE command to specify a source 
directory search list. 

If you issue the SET SOURCE command without the /MODULE=module- 
name qualifier, the debugger uses the specified directory search list to locate 
source files for all modules that were not mentioned in a previous SET 
SOURCE/MODULE=module-name command. 

See the qualifier descriptions for an explanation of their effects. 
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SET SOURCE 


The /EDIT qualifier is needed when the files used for the display of source 
code are different from the files to be edited by means of the EDIT command. 
This is the case with Ada programs. For Ada programs, the (SET, SHOW, 
CANCEL) SOURCE commands affect the search of files used for source 
display (the "copied" source files in Ada program libraries); the (SET, SHOW, 
CANCEL) SOURCE/EDIT commands affect the search of the source files you 
edit when using the EDIT command. If you use /MODULE with /EDIT, the 
effect of /EDIT is further qualified by /MODULE. 

Related commands: (CANCEL, SHOW) SOURCE, (CANCEL, SHOW) MAX_ 
SOURCE—FILES. 


EXAMPLES 

Q DBG> SHOW SOURCE 

no directory search list in effect 

DBG> SET SOURCE [PROJA],[PROJB],USER#:[PETER.PROJC] 

DBG> SHOW SOURCE 

source directory search list for all modules: 

[PROJA] 

[PROJB] 

USER$:[PETER.PROJC] 

The SET SOURCE command specifies that the debugger should search 
directories [PROJA], [PROJB], and USER$:[PETER.PROJC] for source files. 

Q DBG> SET SOURCE/MODULE*COBOLTEST DISK$2:[PROJD].[014,016] 

DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

DISK$2:[PROJD] 

[014,015] 

source directory search list for all other modules: 

[PROJA] 

[PROJB] 

USERS:[PETER.PROJC] 

The SET SOURCE command specifies that the debugger should search 
directories DISKS2:[PROJD] and [014,015]) for source files to use with the 
module COBOLTEST. The SHOW SOURCE command displays the search 
lists established in examples 1 and 2. 
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SET STEP 

Establishes default qualifiers (/LINE, /INTO, and so on) for the STEP 
command. 


FORMAT SET STEP step-default[, . . . 


PARAMETERS step-default 

Specifies a default to be established for the STEP command. Valid keywords 
(which correspond to STEP command qualifiers) are the following: 

BRANCH Subsequent STEP commands will be treated as STEP/BRANCH 


CALL 

(step to the next branch instruction). 

Subsequent STEP commands will be treated as STEP/CALL 
(step to the next call instruction). 

EXCEPTION 

Subsequent STEP commands will be treated as STEP 
/EXCEPTION (step to the next exception condition). 

INSTRUCTION 

Subsequent STEP commands will be treated as STEP 
/INSTRUCTION (step to the next instruction). This is the default 
for MACRO. You can also specify one or more instructions 
(INSTRUCTION=(opcode-list)). The debugger will then step to 
the next instruction that is in the specified list. 

INTO 

Subsequent STEP commands will be treated as STEP/INTO 
(step into called routines) rather than STEP/OVER (step over 
called routines). When INTO is in effect, you can qualify 
the types of routines to step into by means of the [NO]JSB, 
[NO]SHARE, and [NO]SYSTEM parameters, or by using the 
STEP/[NO]JSB, STEP/[NO]SHARE, and STEP/[NO]SYSTEM 
command/qualifier combinations (the latter three take effect 
only for the immediate STEP command). 

JSB 

If INTO is in effect, subsequent STEP commands will be 
treated as STEP/INTO/JSB (step into routines called by a JSB 
instruction as well as those called by a CALL instruction). This 
is the default for all languages except DIBOL. 

NOJSB 

If INTO is in effect, subsequent STEP commands will be treated 
as STEP/INTO/NOJSB (step over routines called by a JSB 
instruction, but step into routines called by a CALL instruction). 
This is the default for DIBOL. 

LINE 

Subsequent STEP commands will be treated as STEP/LINE 
(step to the next line). This is the default for all languages 
except MACRO. 

OVER 

Subsequent STEP commands will be treated as STEP/OVER 
(step over all called routines) rather than STEP/INTO (step into 
called routines). SET STEP OVER is the default. 

RETURN 

Subsequent STEP commands will be treated as STEP/RETURN 
(step to the RETURN instruction of the current routine). Thus, 
STEP/RETURN n will take you up n levels of the call stack. 
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SHARE If INTO is in effect, subsequent STEP commands will be treated 

as STEP/INTO/SHARE (step into called routines in shareable 
images as well as into other called routines). This is the default. 


NOSHARE 

SILENT 

NOSILENT 

SOURCE 

NOSOURCE 

SYSTEM 

NOSYSTEM 


If INTO is in effect, subsequent STEP commands will be treated 
as STEP/INTO/NOSHARE (step over called routines in shareable 
images, but step into other routines). 

Subsequent STEP commands will be treated as STEP/SILENT 
(suppress the "stepped to ... message as well as other 
debugger output). 

Subsequent STEP commands will be treated as STEP 
/NOSILENT (display the "stepped to ... " message as well 
as other output). This is the default. 

Subsequent STEP commands will be treated as STEP/SOURCE 
(display source code after a step as well as when a breakpoint 
or watchpoint is activated). This is the default. 

Subsequent STEP commands will be treated as STEP 
/NOSOURCE (do not display source code after a step or 
when a breakpoint or watchpoint is activated). 

If INTO is in effect, subsequent STEP commands will be treated 
as STEP/INTO/SYSTEM (step into called routines in system 
space (PI space) as well as into other called routines). This is 
the default. 

If INTO is in effect, subsequent STEP commands will be treated 
as STEP/INTO/NOSYSTEM (step over called routines in system 
space, but step into other routines). 


QUALIFIERS None. 


DESCRIPTION The SET STEP command establishes default qualifiers for subsequent STEP 

commands. The parameters that you specify in the SET STEP command have 
the same names as the STEP command qualifiers. The following parameters 
affect the locations to which you step: 


SET STEP 
SET STEP 
SET STEP 
SET STEP 
SET STEP 
SET STEP 
SET STEP 


BRANCH 

CALL 

EXCEPTION 

INSTRUCTION 

INSTRUCTION=(opcode-list) 

LINE 

RETURN 


The following parameters affect what output is seen when a STEP command 
is executed: 

SET STEP [NO]SILENT 
SET STEP [NO]SOURCE 

The following parameters affect what happens at a routine call: 

SET STEP INTO 
SET STEP [NO]JSB 
SET STEP OVER 
SET STEP [NO]SHARE 
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SET STEP [NOJSYSTEM 

Each language establishes certain defaults for the STEP command. When you 
change the current language, STEP defaults are set to those specified in that 
language. 

You can override the current STEP defaults for the duration of a single STEP 
command by specifying other qualifiers. Use the SHOW STEP command to 
identify the current STEP defaults. 

Related commands: STEP, SHOW STEP, (SET, SHOW) LANGUAGE. 


EXAMPLES 

Q DBG> SET STEP INSTRUCTION,NOSOURCE 

This command tells the debugger to step by instruction when a STEP 
command is issued, and to not display lines of source code with each STEP 
command. 

B DBG> SET STEP LINE,INTO.NOSYSTEM,NOSHARE 

This command tells the debugger to step by line when a STEP command is 
issued, and to step into called routines in user space only. The debugger will 
step over routines in system space and in shareable images. 
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SET TASK 


Modifies characteristics of one or more tasks or of the entire tasking 
system. 

Note: The SET TASK command currently applies only to Ada programs. See 
the VAX Ada documentation for complete information. 


FORMAT SET TASK [task-expressionf, ... 77 


PARAMETERS task-expression 

Specifies a task value. A task expression may be: 

• An Ada language expression for a task value—for example, a task object 
name. You can use a path name. 

• The task ID (for example, %TASK 2), as indicated in a SHOW TASK 
display. 

• A pseudo-task name (% ACTIVE _TASK, % CALLER _TASK, %NEXT_ 
TASK, or % VISIBLE—TASK). 

Do not use the wildcard character (*). See the qualifier descriptions for 
details on how to specify tasks with particular qualifiers. 


QUALIFIERS /ABORT 

Aborts the specified tasks. If no task is specified, aborts the visible task. Note 
that the task is marked for termination but is not immediately terminated. 
The effect is identical to executing the Ada statement abort task-name, and 
causes the specified tasks to become abnormal. 

/ACTIVE 

Makes the specified task the active task—the task that will run when a STEP 
or GO command is executed. Causes a task switch to the new active task 
and makes the new active task the visible task. The specified task must be 
in either the RUNNING or READY state. When using /ACTIVE, you must 
specify one, and only one, task. 

/ALL 

Applies the SET TASK command to all tasks. When you specify /ALL, 
you cannot specify a task, nor can you specify the /ACTIVE, /VISIBLE, or 
/TIME-SLICE qualifiers. 

/[NOJHOLD 

Controls whether or not a specified task is placed on HOLD. /HOLD places a 
specified task on HOLD. If no task is specified, /HOLD places the visible task 
on HOLD. 

Placing a task on HOLD prevents a task from entering the RUNNING 
state. A task placed on HOLD is allowed to make other state transitions; in 
particular, it may change from the SUSPENDED to the READY state. 
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A task that is already in the RUNNING state (the active task) can continue to 
execute as long as it remains in the RUNNING state, even though it is placed 
on HOLD. If the task leaves the RUNNING state for any reason (including 
expiration of a time slice, if timeslicing is enabled), it may not return to the 
RUNNING state until the HOLD is removed. You can force a task into the 
RUNNING state with the SET TASK/ACTIVE command even if the task is 
on HOLD. 

/NOHOLD removes a specified task from HOLD. If no task is specified, 
/NOHOLD removes the visible task from HOLD. 

/PR I OR I TY=n 

Sets the priority of a specified task to n, where n is a decimal integer from 0 
to 15 inclusive. If no task is specified, sets the priority of the visible task to n. 
Note that this does not prevent the task's priority from later changing in the 
course of execution, for example, while executing a rendezvous. 

/RESTORE 

Causes the priority of a specified task to be restored to the value specified in 
pragma PRIORITY. If pragma PRIORITY was not specified, the default value 
of 7 is used. If no task is specified, causes the priority of the visible task to be 
restored. 

/TIME_SLICE=t 

Sets the duration otherwise specified by pragma TIME—SLICE to the value 
t, where t is a decimal integer or fixed-point value representing seconds. The 
SET TASK/TIME—SLICE=0.0 command disables time slicing. 

/VISIBLE 

Makes the specified task the visible task—the task whose stack and register 
set are the current context for looking up names, calls, and so on (commands 
such as EXAMINE are directed at the visible task). When using /VISIBLE, 
you must specify one, and only one, task. 

Note: If no qualifier is specified, /VISIBLE is assumed by default. 


DESCRIPTION The possible task states are RUNNING, READY, SUSPENDED, and 

TERMINATED. 

All of the SET TASK command qualifiers except for /ALL provide a means 
of controlling the tasking environment, by directly or indirectly causing task 
state transitions. The /ALL qualifier is used to apply the SET TASK command 
to all tasks. 

Task switching can often be confusing when you are trying to debug a 
program. The SET TASK/TIME-SLICE and SET TASK/HOLD commands 
give you several ways of controlling task switching. 

Related commands: SHOW TASK, SET BREAK/EVENT, SET TRACE 
/EVENT, EXAMINE/TASK, DEPOSIT/TASK. 
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EXAMPLES 

Q DBG> SET TASK/ACTIVE ‘/.TASK 3 

This command makes the task whose task ID is %TASK 3 the active task. 

Q DBG> SET TASK/HOLD/ALL 

DBG> SET TASK/ACTIVE ‘/.TASK 1 
DBG> GO 


DBG> SET TASK/ACTIVE '/.TASK 3 
DBG> STEP 


The SET TASK/HOLD/ALL command freezes the state of all tasks except the 
active task. The SET TASK/ACTIVE command is then used selectively (along 
with the GO command) to observe the behavior of one or more specified 
tasks in isolation. 
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SET TERMINAL 


Sets the terminal screen width and/or height that the debugger uses 
when it formats screen and other output. 


FORMAT SET TERMINAL 


PARAMETERS None. 


QUALIFIERS You must specify at least one qualifier, either /PAGE or /WIDTH. You can 

specify both /PAGE and /WIDTH. You must specify a value for each qualifier 
used. 

/PAGE.n 

Specifies that the terminal screen height should be set to n lines. You may 
use any value from 18 to 100. 

/WIDTH.n 

Specifies that the terminal screen width should be set to n columns. You may 
use any value from 20 to 255. For a VT100 or VT200 series terminal, n is 
typically either 80 or 132. 


DESCRIPTION The SET TERMINAL command lets you define the portion of the screen that 

the debugger has available for formatting screen output. This command is 
particularly useful with VT100 or VT200 series terminals, where you may 
set the screen width to typically 80 or 132 columns. It is also useful with 
Micro VAX workstations, where you can increase the screen size beyond the 
default 24-line by 80-column DEBUG window. 

When you issue the SET TERMINAL command, all screen window definitions 
(including those created by the user) are automatically adjusted for the new 
screen dimensions. For example, RH1 will change dimensions proportionally 
to remain the top right half of the screen. 

Similarly, all "dynamic" displays are automatically adjusted to maintain their 
relative dimensions. By default, all predefined and user-defined displays are 
dynamic, except for register displays. If you have specified /NODYNAMIC 
in a SET DISPLAY or DISPLAY command, the display is no longer dynamic. 
In that case, the display will not automatically change dimensions with a 
SET TERMINAL command. However, you can always use the DISPLAY 
command to redisplay the display within any window definition (you can 
also use keypad-key combinations, such as BLUE-MINUS, to enter predefined 
DISPLAY commands). 

Related commands: SHOW TERMINAL, DISPLAY/[NOjDYNAMIC, SET 
DISPLAY/[NOJDYNAMIC, (SET, SHOW, CANCEL) WINDOW, EXPAND. 
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EXAMPLE 


DBG> set TERMINAL/WIDTH:132 


This command specifies that the terminal screen width be set to 132 columns. 
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SET TRACE 


Establishes a tracepoint at the location denoted by an address- 
expression, or at instructions of a particular class. 


FORMAT SET TRACE [addr-expr[, . . . ]] [WHEN (con d-expr)] 

[DO (commandf; ...])] 


PARAMETERS addr-expr 

Specifies an address expression (a program location) at which a tracepoint 
is to be set. In general, this may be a line number, a routine name, a label, 
or a location in memory. However, the /MODIFY and /RETURN qualifiers 
are used with specific kinds of address expressions. Do not use the wildcard 
character (*). Do not use an address expression when specifying /BRANCH, 
/CALL, /EXCEPTION, /INSTRUCTION[=(opcode-list)], /INTO, /[NO]JSB, 
/LINE, /OVER, /[NOjSHARE, or /[NO]SYSTEM. 

command 

Specifies a debugger command that is to be executed as part of the DO clause 
when trace action is taken. 

cond-expr 

Specifies a conditional expression in the currently set language that is to be 
evaluated every time the tracepoint occurs. If the expression is TRUE, trace 
action occurs, and the debugger reports that a tracepoint has been reached. If 
the expression is FALSE, trace action does not occur. In this case, a report is 
not issued, the commands specified by the DO clause are not executed, and 
program execution is continued. 


QUALIFIERS /AFTERm 

Specifies that trace action not be taken until the nth time the designated 
tracepoint is encountered (n is a decimal integer). Thereafter, the tracepoint 
occurs every time it is encountered provided that conditions in the WHEN 
clause are TRUE. The command SET TRACE/AFTER:1 has the same effect as 
the SET TRACE command. 

/BRANCH 

Causes the debugger to trace every branch instruction encountered (including 
BEQL, BGTR, BLEQ, BGEQ, BLSS, BGTRU, BLEQU, BVC, BVS, BGEQU, 
BLSSU, BRB, BRW, JMP, BBS, BBC, BBSS, BBCS, BBSC, BBCC, BBSSI, BBCCI, 
BLBS, BLBC, ACBB, ACBW, ACBL, ACBF, ACBD, ACBG, ACBH, AOBLEQ, 
AOBLSS, SOBGEQ, SOBGTR, CASEB, CASEW, CASEL) during execution. 

Do not specify an address expression with this qualifier. See also /INTO, 
/OVER. 
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/CALL 

Causes the debugger to trace every call instruction (including the CALLS, 
CALLG, BSBW, BSBB, JSB, RSB, and RET instructions) encountered during 
execution. Do not specify an address expression with this qualifier. See also 
/INTO, /OVER. 

/EVENT=event-name 


Note: /EVENT applies only to Ada and SCAN. See the VAX Ada and VAX 
SCAN documentation for complete information. 

Causes the debugger to trace every time the specified event occurs (if that 
event is defined and detected by the run-time system). If you specify an 
address expression with /EVENT, causes the debugger to trace every time 
the specified event occurs for that address expression. Event names depend 
on the run-time facility and are identified in Appendix E for Ada and SCAN. 
Note that you cannot specify an address expression with certain event names. 

/EXCEPTION 

Causes the debugger to trace every exception that is signaled. The trace 
action occurs before any user-written exception handlers are invoked. Do not 
specify an address expression with this qualifier. 

/INSTRUCTION 

Causes the debugger to trace every instruction executed. Do not specify an 
address expression with this qualifier. See also /INTO, /OVER. 

/INSTRUCTION=(opcode[ r . . . ]) 

Causes the debugger to trace every instruction whose opcode is in the list. 

Do not specify an address expression with this qualifier. See also /INTO, 
/OVER. 

/INTO 

Sets tracepoints within called routines (as well as within the main program) 
when /BRANCH, /CALL, /INSTRUCTION=[(opcode-list)], or /LINE is 
specified; that is, when an address expression is not explicitly specified. 
/INTO is the default behavior and is the opposite of /OVER. When 
using /INTO, you can further qualify the tracepoints with the /[NO]JSB, 
/[NO]SHARE, and /[NO]SYSTEM qualifiers. 

/[NOJJSB 

Qualifies /INTO. Use /[NO]JSB with /INTO and one of these qualifiers: 
/BRANCH, /CALL, /INSTRUCTION[=(opcode-list)], or /LINE. /JSB is the 
default for all languages except DIBOL. /JSB lets the debugger set tracepoints 
within routines that are called by the JSB or CALL instruction. /NOJSB 
(the DIBOL default) specifies that tracepoints not be set within routines 
called by JSB instructions. In DIBOL, user-written routines are called by the 
CALL instruction and DIBOL run-time library routines are called by the JSB 
instruction. Do not specify an address expression with this qualifier. 


/LINE 

Causes the debugger to trace the start of each new line. Do not specify an 
address expression with this qualifier. See also /INTO, /OVER. 
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/MODIFY 

Causes the debugger to report a tracepoint whenever an instruction writes 
to and modifies the value of a location indicated by a specified address 
expression. The address expression is typically a variable name. 

The SET TRACE/MODIFY command acts like a SET WATCH command 
followed by a GO command. It operates under the same restrictions as the 
SET WATCH command. 

If you specify an absolute address for the address expression, the debugger 
may not be able to associate the address with a particular data object. In 
this case, the debugger uses a default length of 4 bytes. You can change this 
length, however, by setting the type to either WORD (which changes the 
default length to 2 bytes) or BYTE (which changes the default length to 1 
byte). 

/OVER 

Sets tracepoints only within the main program (not within called routines) 
when /BRANCH, /CALL, /INSTRUCTION=[(opcode-list)], or /LINE is 
specified; that is, when an address expression is not explicitly specified. 
/OVER is the opposite of /INTO. 

/RETURN 

Sets a tracepoint on the RETURN (RET) instruction from an indicated routine. 
This qualifier can only be applied to routines called with a CALLS or CALLG 
instruction; it cannot be used with JSB routines. 

For this qualifier, the address-expression parameter is an instruction address 
within a CALLS or CALLG routine. It may simply be a routine name, in 
which case it specifies the routine start address. However, you can also 
specify another location in a routine, so you can see only those returns that 
are taken after a certain code path is followed. 

/[NOJSHARE 

Qualifies /INTO. Use /[NOjSHARE with /INTO and one of these qualifiers: 
BRANCH, /CALL, /INSTRUCTION[=(opcode-list)], or /LINE. /SHARE 
(default) lets the debugger set a tracepoint within shareable image routines 
as well as other routines. /NOSHARE specifies that tracepoints not be set 
within shareable images. Do not specify an address expression with this 
qualifier. 

/[l\IO]SILEI\IT 

Controls whether or not the "trace ..." message (and source code) is 
displayed when trace action is taken. /NOSILENT (default) specifies that 
the message be displayed. /SILENT specifies that no message or source code 
be displayed. /SILENT overrides /SOURCE. 

/[NOJSOURCE 

Controls whether or not the source code is displayed when trace action 
is taken. /SOURCE (default) specifies that the source code be displayed. 
/NOSOURCE specifies that no source code be displayed. /SILENT overrides 
/SOURCE. 
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/[NOJSYSTEM 

Qualifies /INTO. Use /[NOJSYSTEM with /INTO and one of these qualifiers: 
/BRANCH, /CALL, /INSTRUCTION[=(opcode-list)J, or /LINE. /SYSTEM 
(default) lets the debugger set tracepoint within system routines (PI space) 
as well as other routines. /NOSYSTEM specifies that tracepoints not be 
set within system routines. Do not specify an address expression with this 
qualifier. 

/TEMPORARY 

Causes the tracepoint to disappear after it is activated (the tracepoint does not 
remain permanently set). 


DESCRIPTION When a tracepoint is activated, the debugger takes the following action: 

1 Suspends program execution at the tracepoint location. 

2 Evaluates the expression in a WHEN clause, if one was specified when 
the tracepoint was set. If the value of the expression is FALSE, execution 
continues and the debugger does not perform the next two steps. 

3 Reports that execution has reached the tracepoint location, unless 
/SILENT was specified. 

4 Executes the commands in a DO clause, if one was specified when the 
tracepoint was set. 

5 Resumes execution. 

The following qualifiers affect what output is seen when a tracepoint is 
reached: 

/[NOJSILENT 

/[NOJSOURCE 

The following qualifiers affect the timing and duration of tracepoints: 

/AFTER:n 

/TEMPORARY 

Tracepoints may be set on classes of instructions by using one of the 
following qualifiers: 

/BRANCH 

/CALL 

/EVENT=event-name 

/EXCEPTION 

/INSTRUCTION 

/INSTRUCTION=(opcode-list) 

/LINE 

/RETURN 

The following qualifiers affect what happens at a routine call: 

/INTO 

/[NOJJSB 

/OVER 

/[NOJSHARE 

/[NOJSYSTEM 
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The /MODIFY qualifier is used to monitor changes at program locations 
(typically changes in the values of variables). 

Related commands: (SHOW, CANCEL) TRACE, CANCEL ALL, SET BREAK, 
SET WATCH, GO, (SET, SHOW) EVENT-FACILITY. 


EXAMPLES 

Q DBG> SET TRACE SUB1 

This command sets a tracepoint at location (routine) SUB1. 

B DBG> SET TRACE/SILENT COUNTER WHEN (A = B) DO (EXAMINE Y) 

This command sets a tracepoint on routine COUNTER that will trigger only 
when A equals B. When the tracepoint is triggered, variable Y is examined. 
The /SILENT qualifier suppress the "trace ..." message. 

E DBG> SET TRACE/BRANCH 

This command causes the debugger to trace every branch instruction. 

Q DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM 

This command causes the debugger to trace every line, including lines in 
called routines, but not in shareable image routines or system routines. 
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SET TYPE 


Establishes the default type to be associated with program locations 
that do not have a compiler generated type. When used with 
/OVERRIDE, establishes the default type to be associated with all 
locations, overriding any compiler generated types. 


FORMAT SET TYPE type-keyword 


PARAMETERS 


type-keyword 

Specifies the default type to be established. Valid keywords are the following: 


ASCIC 

ASCID 


ASCILn 


ASCIW 

ASCIZ 

BYTE 

DATE-TIME 

D-FLOAT 

FLOAT 

G-FLOAT 


Sets the default type to counted ASCII string. AC is 
also accepted as a keyword. 

Sets the default type to ASCII string descriptor. The 
CLASS and DTYPE fields of the descriptor are not 
checked, but the LENGTH and POINTER fields provide 
the character length and address of the ASCII string. 
The string is then displayed. AD is also accepted as a 
keyword. 

Sets the default type to ASCII character string (length n 
bytes). The length indicates both the number of bytes 
of memory to be examined and the number of ASCII 
characters to be displayed. If you do not specify a 
value for n, the debugger uses the default value of 4 
bytes. The value n is interpreted in decimal radix. 

Sets the default type to ASCII varying string (a 2-byte 
length field immediately followed by an ASCII string 
of that length). This data type occurs in PASCAL and 
PL/I. AW is also accepted as a keyword. 

Sets the default type to zero-terminated ASCII string. 
AZ is also accepted as a keyword. 

Sets the default type to byte integer (length 1 byte). 

Sets the default type to date-time: a quadword integer 
(length 64 bits) containing the internal VAX/VMS 
representation of date-time. 

Sets the default type to D_floating (length 8 bytes). 
Values of type D_floating may range from .29*10~ 38 
to 1.7*10 38 with approximately 16 decimal digits 
precision. 

Sets the default type to F_floating (length 4 bytes). 
Values of type F_floating may range from .29*10~ 38 to 
l.7*10 38 with approximately 7 decimal digits precision. 

Sets the default type to G_floating (length 8 bytes). 
Values of type G_floating may range from . 56*10~ 308 
to .9*10 308 with approximately 15 decimal digits 
precision. 
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H _FLOAT 


INSTRUCTION 

LONGWORD 

OCTAWORD 

PACKED:n 

QUADWORD 

TYPE=(expression) 

WORD 


Sets the default type to H_floating (length 16 bytes). 
Values of type H_floating may range from .84*10~ 4932 
to .59*10 4932 with approximately 33 decimal digits 
precision. 

Sets the default type to VAX instruction (variable 
length, depending on the number of instruction 
operands and the kind of addressing modes used). 

Sets the default type to longword integer (length 4 
bytes). This the default for all languages. 

Sets the default type to octaword integer (length 16 
bytes). 

Sets the default type to packed decimal (length 4n 
bits). 

Sets the default type to quadword integer (length 8 
bytes). 

Sets the default type to the type denoted by 
expression. Expression may be the name of an existing 
program variable or data type. 

Sets the default type to word integer (length 2 bytes). 


QUALIFIERS /OVERRIDE 

Associates the type specified with all program locations, not just those that 
have a compiler-generated type. 


□ ASCRIPTION When you use the EXAMINE, DEPOSIT, or EVALUATE commands, the 

default types associated with address expressions influence how program 
entities are interpreted and displayed. 

The debugger recognizes any compiler generated types associated with 
program locations and interprets and displays the contents of these locations 
accordingly. For program locations that do not have a compiler generated 
type, the default type in all languages is longword integer. 

The SET TYPE command lets you change the default type associated with 
untyped program locations. The SET TYPE/OVERRIDE command lets you 
set a default type for all program locations, not just untyped locations. 

Note that the EXAMINE and DEPOSIT commands have type qualifiers 
that let you further override, for the duration of that command, any 
type previously established with the SET TYPE or SET TYPE/OVERRIDE 
command. 

Related commands: SHOW TYPE, CANCEL TYPE/OVERRIDE, (SET, 
SHOW, CANCEL) RADIX, (SET, SHOW, CANCEL) MODE. 


EXAMPLES 

Q DBG> SET TYPE ASC:8 


This command establishes 8-byte ASCII character string as the default type 
associated with untyped program locations. 
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B DBG> set type/override longword 

This command establishes longword integer as the default type associated 
with both untyped program locations and program locations that have 
compiler-generated types. 


0 DBG> SET TYPE D.FLOAT 


This command establishes D__Floating as the default type associated with 
untyped program locations. 

Q DBG> SET TYPE TYPE*(S_ARRAY) 

This command establishes the type of the variable S—ARRAY as the default 
type associated with untyped program locations. 
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SET WATCH 



Establishes a watchpoint at the location denoted by an address- 
expression. 

FORMAT 

SET WATCH [addr-expr[, ...]][ 

WH E N(cond-expr)] [ 

DO(command[; ...])] 


PARAMETERS addr-expr 

Specifies an address expression (a program location) at which a watchpoint is 



to be set. For high-level languages, this is typically the name of a variable. 

Do not use the wildcard character (*). 

command 

Specifies a debugger command that is to be executed as part of the DO clause 
when watch action is taken. 

cond-expr 

Specifies a conditional expression in the currently set language that is to be 
evaluated every time the watchpoint occurs. If the expression is TRUE, watch 
action occurs, and the debugger reports that a watchpoint has been triggered. 
If the expression is FALSE, watch action does not occur. In this case, a report 
is not issued, the commands specified by the DO clause are not executed, and 
program execution is continued. 

QUALIFIERS 

/AFTER :n 

Specifies that watch action not be taken until the nth time the designated 
watchpoint is encountered (n is a decimal integer). Thereafter, the watchpoint 
occurs every time it is encountered provided that conditions in the WHEN 
clause are TRUE. The command SET WATCH/AFTER:1 has the same effect 
as the SET WATCH command. 

/[NOJSILENT 

Controls whether or not the "watch ..." message (and source code) is 
displayed when watch action is taken. /NOSILENT (default) specifies that 
the message be displayed. /SILENT specifies that no message or source code 
be displayed. /SILENT overrides /SOURCE. 

/[NOJSOURCE 

Controls whether or not the source code is displayed when watch action 
is taken. /SOURCE (default) specifies that the source code be displayed. 
/NOSOURCE specifies that no source code be displayed. /SILENT overrides 
/SOURCE. 
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/TEMPORARY 

Causes the watchpoint to disappear after it is activated (the watchpoint does 
not remain permanently set). 


DESCRIPTION Whenever an instruction causes the modification of a watched location, the 

debugger takes the following action: 

1 Suspends program execution after that instruction has completed 
execution. 

2 Evaluates the expression in a WHEN clause, if one was specified when 
the watchpoint was set. If the value of the expression is FALSE, execution 
continues and the debugger does not perform the following steps. 

3 Reports that execution has reached the watchpoint location, unless 
/SILENT was specified. 

4 Reports the value at the watched location before modification. 

5 Reports the new or modified value at the watched location. 

6 Identifies the instruction that modified the watched location. Also, 
displays the line of source code corresponding to that instruction if 
the SOURCE parameter is in effect by virtue of a previous SET STEP 
SOURCE command. 

7 Executes the commands in a DO clause, if one was specified when the 
watchpoint was set. If the DO clause contains a GO command, execution 
continues and the debugger does not perform the next step. 

8 Issues the DBG> prompt. 

If the watched location has a compiler-generated type, the debugger uses the 
length in bytes associated with that type to determine the length in bytes 
of the watched location. If the watched location does not have a compiler¬ 
generated type, the debugger watches four bytes of virtual memory beginning 
at the byte identified by the address expression. 

You can set watchpoints on aggregates (that is, entire arrays or records). A 
watchpoint set on an array or record will trigger if any element of the array 
or record changes. Thus, you do not need to set watchpoints on individual 
array elements or record components. Note, however, that you cannot set an 
aggregate watchpoint on a variant record. 

You cannot set a watchpoint on a variable that is on the stack or that is 
allocated to a register. 

Related commands: (SHOW, CANCEL) WATCH, SET BREAK, SET TRACE. 


EXAMPLES 

□ DBG> SET WATCH MAXCOUNT 

This command establishes a watchpoint at location MAXCOUNT. 
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Q DBG> SET WATCH ARR 
DBG> GO 


watch of SUBR\ARR at SUBR\7.LINE 12+8 


old value: 


(1) 

7 

(2) 

12 

(3) 

3 

new value: 

(1) 

7 

(2) 

12 

(3) 

28 


break at SUBRV/.LINE 14 

In this example, the SET WATCH command sets a watchpoint on the 
three-element integer array, ARR. Execution is then resumed with the GO 
command. The watchpoint is triggered whenever any array element changes. 
In this case the third element changed. 
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SET WINDOW 



Creates a screen window definition. 

FORMAT 

SET WINDOW wname AT (start-line,line-count 

[, start-col, col-count]) 


PARAMETERS wname 

Specifies the name of the window you are defining. If a window definition 



with that name already exists, it is canceled in favor of the new definition. 

start-line 

Specifies the starting line number of the window. This line displays the 
window title, or header line. The top line of the screen is line 1. 

line-count 

Specifies the number of text lines in the window, not counting the header 
line. Line-count must be at least 1. The sum of start-line and line-count must 
not exceed the current screen height. 

start-col 

Specifies the starting column number of the window. This is the column 
at which the first character of the window will be displayed. The leftmost 
column of the screen is column 1. 

col-count 

Specifies the number of characters per line in the window. Col-count must 
be at least 1. The sum of start-col and col-count must not exceed the current 
screen width. 

QUALIFIERS 

None. 

DESCRIPTION 

A screen window is a rectangular region on the terminal screen through 
which you may view a display. The SET WINDOW command establishes a 
window definition by associating a window name with a screen region. You 
specify the screen region in terms of a starting line and height (line count) 
and, optionally, a starting column and width (column count). If you do not 
specify the starting column and column count, they default to column 1 and 
the current screen width. 

You can specify a window region in terms of expressions that use the built-in 
symbols %PAGE and %WIDTH. 

You can use the names of any windows you have defined with the SET 
WINDOW command in DISPLAY and SET DISPLAY commands to position 
displays on the screen. 
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SET WINDOW 


Window definitions are "dynamic"—that is, window dimensions expand and 
contract proportionally when a SET TERMINAL command changes the screen 
width or height. 

Related commands: (SHOW, CANCEL) WINDOW, (SET SHOW, CANCEL) 
DISPLAY, DISPLAY, (SET, SHOW) TERMINAL. 


EXAMPLES 

Q DBG> SET WINDOW ONELINE AT (1.1) 

This command defines a window named ONELINE at the top of the screen. 
The window is one line deep and, by default, spans the width of the screen. 

0 DBG> SET WINDOW MIDDLE AT (9,4,30,20) 

This command defines a window named MIDDLE at the middle of the screen. 
The window is 4 lines deep starting at line 9, and 20 columns wide starting at 
column 30. 

0 DBG> SET WINDOW FLEX AT (7.PAGE/4,*/.PAGE/2,y.WIDTH/4,y.WIDTH/2) 

This command defines a window named FLEX that occupies a region around 
the middle of the screen and is defined in terms of the current screen height 
(%PAGE) and width (%WIDTH). 
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SHOW AST 

Indicates whether delivery of ASTs is enabled or disabled. 

FORMAT 

SHOW AST 

PARAMETERS 

None. 

QUALIFIERS 

None. 

DESCRIPTION 

The SHOW AST command indicates whether delivery of ASTs is enabled or 
disabled. Note that the command does not identify an AST whose delivery is 
pending. The delivery of ASTs is enabled by default and with the ENABLE 
AST command. The delivery of ASTs is disabled with the DISABLE AST 
command. 

Related commands: (ENABLE, DISABLE) AST. 

EXAMPLE 



DBG> SHOW AST 
ASTs are enabled 
DBG> DISABLE AST 
DBG> SHOW AST 
ASTs are disabled 
DBG> 

The SHOW AST command indicates whether the delivery of ASTs is enabled. 
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SHOW ATSIGN 


SHOW ATSIGN 



Identifies the default file specification established with the last SET 
ATSIGN command. The debugger uses this file specification when 
processing the @file-spec command. 

FORMAT 

SHOW ATSIGN 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

Related commands: SET ATSIGN, @file-spec. 


EXAMPLES 

Q DBG> SHOW ATSIGN 

No indirect command file default in effect, using DEBUG.COM 

If the SET ATSIGN command was not used, the debugger assumes 
that command procedures have the default file specification 
SYS$DISK:[ ]DEBUG.COM. 

Q DBG> SET ATSIGN USER:[JONES.DEBUG].DBG 
DBG> SHOW ATSIGN 

Indirect command file default is USER:[JONES.DEBUG].DBG 

The SHOW ATSIGN command indicates the default file specification for 
command procedures, as previously established with the SET ATSIGN 
command. 
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SHOW BREAK 


SHOW BREAK 



Displays information about all breakpoints established by the SET 
BREAK command, including WHEN and DO clauses and /AFTER 
counts. 

FORMAT 

SHOW BREAK 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The debugger displays all information about each breakpoint that is currently 
set, including any optional WHEN and DO clauses. 

If you established a breakpoint using the /AFTER:n command qualifier with 
the SET BREAK command, the SHOW BREAK command displays the current 
value of the decimal integer n, that is, the originally specified integer value 
minus one for each time the breakpoint location was reached. (The debugger 
decrements n each time the breakpoint location is reached until the value of n 
is zero, at which time the debugger takes break action.) 

Related commands: (SET, CANCEL) BREAK. 


EXAMPLE 

DBG> SHOW BREAK 
breakpoint at SUB1\L00P 
breakpoint at MAIN\MAIN+1F 

do (EX SUB1\D ; EX/SYMBOL PSL; GO) 
breakpoint at routine SUB2\SUB2 
/after: 2 

This command displays information about the three breakpoints currently set, 
SUBl\LOOP, MAIN\MAIN, and SUB2\SUB2. 


CD-149 









SHOW CALLS 


SHOW CALLS 


Identifies the currently active routine calls (the call stack). 


FORMAT 

SHOW CALLS [n] 

PARAMETERS 

n 

Specifies the number of call frames to be identified. If n is omitted, all 
currently active call frames are identified. 

QUALIFIERS 

None. 

DESCRIPTION 

The SHOW CALLS command shows a traceback that lists the sequence 
of routine calls leading to the currently executing routine. One line of 
information is displayed for each call frame, starting with the most recent 
call. The top line identifies the currently executing routine, the next line 
identifies its caller, the following line identifies the caller of the caller, and so 
on. 


The following information is provided for each call frame: 

• The name of the enclosing module. 


• The name of the calling routine, provided the module is set (the first line 
shows the currently executing routine). 


• The line number where the call was made in that routine, provided the 
module is set (the first line shows the line number where execution is 
suspended). 


• The value of the PC in the calling routine at the time that control was 
transferred to the called routine. The PC value is shown as a virtual 
address relative to the virtual address of the name of the routine and also 
as an absolute virtual address. 


Related commands: SHOW STACK, SHOW SCOPE. 


EXAMPLE 


DBG> SHOW CALLS 


module name 

routine name 

line 

rel PC 

abs PC 

SUB2 

SUB2 


00000002 

0000085A 

♦SUB1 

SUB1 

5 

00000014 

00000854 

♦MAIN 

MAIN 

10 

0000002C 

0000082C 


This command displays information about the sequence of currently active 
procedure calls. 

An asterisk next to a module name indicates that the module is set. 
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SHOW DEFINE 


SHOW DEFINE 



Identifies the default qualifier (/ADDRESS, /COMMAND, or /VALUE) 
currently in effect for the DEFINE command. 

FORMAT 

SHOW DEFINE 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The default qualifier for the DEFINE command is the default qualifier last 
established with the SET DEFINE command. If no SET DEFINE command 
was issued, the default qualifier is /ADDRESS. 

To identify a symbol defined with the DEFINE command, use the SHOW 
SYMBOL/DEFINED command. 

Related commands: SET DEFINE, DEFINE, DELETE, SHOW SYMBOL 
/DEFINED. 


EXAMPLE 

DBG> SHOW DEFINE 

Current setting is: DEFINE/ADDRESS 
DBG> 

The SHOW DEFINE command indicates that the DEFINE command is set for 
definition by address. 
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SHOW DISPLAY 


SHOW DISPLAY 

Identifies one or more existing screen displays. 

FORMAT 

SHOW DISPLAY [disp-name[, ... 77 

PARAMETERS 

disp-name 

Specifies the name of a display. If you do not specify a name, or if you 
specify the wildcard character (*) by itself, all display definitions are listed. 
You can use * within a display name. When using /ALL, do not specify a 
display name. 

QUALIFIERS 

/ALL 

Lists all display definitions. When using /ALL, do not specify a display 
name. 

DESCRIPTION 

The SHOW DISPLAY command lists all displays according to their order in 
the display list. The most hidden display is listed first, and the display that is 
on top of the display pasteboard is listed last. 

For each display, the SHOW DISPLAY command lists its name, maximum 
size, screen window, and display kind (including any debug command list). It 
also identifies whether or not the display is removed from the pasteboard or 
is dynamic (a dynamic display automatically adjusts its window dimensions if 
the screen size is changed with the SET TERMINAL command). 

Related commands: (SET, CANCEL) DISPLAY, DISPLAY, (SET, CANCEL, 
SHOW WINDOW), SHOW SELECT, EXTRACT/SCREEN-LAYOUT. 


EXAMPLE 


DBG> SHOW DISPLAY 

display SRC at HI, size = 64, dynamic 

kind = SOURCE (EXAMINE/SOURCE . y,SOURCE_SCOPE\7.PC) 
display INST at HI, size = 64, removed, dynamic 

kind = INSTRUCTION (EXAMINE/INSTRUCTION .0\7.PC) 
display REG at RH1, size = 64, removed, not dynamic, kind = REGISTER 
display OUT at S46, size = 100, dynamic, kind = OUTPUT 
display EXSUM at Q3, size - 64, dynamic, kind = DO (EXAMINE SUM) 
display PROMPT at S6, size = 64, dynamic, kind = PROGRAM 

The SHOW DISPLAY command lists all displays currently defined. These 
include the five predefined displays (SRC, INST, REG, OUT, and PROMPT), 
and the user-defined DO display EXSUM. Displays INST and REG are 
removed from the display pasteboard: the DISPLAY command must be used 
in order to display them on the screen. 
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SHOW EDITOR 


SHOW EDITOR 



Indicates the action taken by the EDIT command, as established by 
the SET EDITOR command. 

FORMAT 

SHOW EDITOR 


PARAMETERS None . 


QUALIFIERS 

None. 

DESCRIPTION 

Related commands: SET EDITOR, EDIT. 


EXAMPLES 

Q DBG> SHOW EDITOR 

The editor is SPAWNed, with command line ' , LSEDIT/START_POSITION=(n,1)" 

The SHOW EDITOR command indicates that, when you issue the EDIT 
command, you will spawn the VAX Language-Sensitive Editor in a 
subprocess. The /START-POSITION qualifier that is appended to the 
command line indicates that the editing cursor will be initially positioned at 
the start of the line that is cented in the debugger's current source display. 

Q DBG> SET EDITOR/CALLABLE.TPU 
DBG> SHOW EDITOR 

The editor is CALLABLE_TPU, with command line "TPU" 

The SHOW EDITOR command indicates that, when you issue the EDIT 
command, you will invoke the callable version of the VAX Text Processing 
Utility (VAXTPU). The editing cursor will be initially positioned at the start of 
source line 1. 


CD—153 












SHOW EVENT-FACILITY 


SHOW EVENT-FACILITY 

Identifies the current run-time facility for eventpoints and the 
associated event names. 

Note: The SHOW EVENT—FACILITY command currently applies only to 



Ada and SCAN. See the VAX Ada and VAX SCAN documentation for 
complete information. 

FORMAT 

SHOW EVENT-FACILITY 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The SHOW EVENT-FACILITY command is meaningful only with Ada or 
SCAN programs. The command identifies the current run-time facility and 
lists the associated event names that may be used with the SET BREAK 
/EVENT and SET TRACE/EVENT commands. The event names associated 
with the Ada and SCAN run-time facilities are identified in Appendix E. 

Related commands: SET EVENT-FACILITY, (SET, CANCEL) BREAK 
/EVENT, SHOW BREAK, (SET, CANCEL) TRACE/EVENT, SHOW TRACE. 


EXAMPLES 

Q DBG> SHOW EVENT-FACILITY 
event facility is ADA 

This command identifies the current event facility to be Ada and lists the 
associated event names that may be used with a SET BREAK/EVENT or SET 
TRACE/EVENT command. 
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SHOW EXIT-HANDLERS 


SHOW EXIT-HANDLERS 


Identifies the exit handlers that have been declared in your program. 

FORMAT 

SHOW EXIT-HANDLERS 

PARAMETERS None. 

QUALIFIERS 

None. 

DESCRIPTION 

The exit handler routines are displayed in the order that they will be called 
(that is, last in, first out). The routine name is displayed symbolically, if 
possible. Otherwise, its address is displayed. The debugger's exit handlers 
are not displayed. 


EXAMPLE 


DBG> SHOW EXIT-HANDLERS 
exit handler at STACKS\CLEANUP 

The SHOW EXIT-HANDLERS command identifies the exit handler routine 
CLEANUP, which is declared in module STACKS. 
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SHOW IMAGE 


SHOW IMAGE 


Displays information about one or more shareable images that are 
part of your running program. 


FORMAT SHOW IMAGE [image-name] 


PARAMETERS image-name 

Specifies the name of a shareable image to be included in the display. If you 
do not specify a name, or if you specify the wildcard character (*) by itself, 
all images are listed. You can use * within an image name. 


QUALIFIERS None. 


DESCRIPTION The SHOW IMAGE command displays the following information: 

• The name of the shareable image 

• The start and end addresses of the image 

• Whether the image has been "set" with the SET IMAGE command (loaded 
into the RST) 

• The current image that is your debugging context (marked with an 
asterisk) 

• The total number of images selected in the display 

Related commands: (SET, CANCEL) IMAGE, (SET, SHOW, CANCEL) 
MODULE. 


EXAMPLES 

Q DBG> SHOW IMAGE SHARE* 


image name 

set 

base address 

end address 

♦SHARE 

yes 

00000200 

00000FFF 

SHARE1 

no 

00001000 

000017FF 

SHARE2 

yes 

00018C00 

00019IFF 

SHARE3 

no 

00019200 

000195FF 

SHARE4 

no 

00019600 

0001B7FF 


total images: 5 remaining size: 33032 


This SHOW IMAGE command identifies all of the shareable images whose 
names start with "SHARE" and which are associated with the program. 
Images SHARE and SHARE2 are set. The asterisk identifies SHARE as the 
current image. 
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SHOW KEY 


SHOW KEY 


Displays the key definitions created by the DEFINE/KEY command. 


FORMAT SHOW KEY [key-name] 


PARAMETERS key-name 

Specifies a function key whose definition is to be displayed. Do not use the 
wildcard character (*). When using /ALL, do not specify a key name. Valid 
key names are the following: 


Keyname 


LK201 

VT100-type 

VT52-type 

PF1 


PF1 

PF1 

Blue 

PF2 


PF2 

PF2 

Red 

PF3 


PF3 

PF3 

Black 

PF4 


PF4 

PF4 


KPO, KP1,. 

. . ,KP9 

Keypad 0, ... ,9 

Keypad 0, ... ,9 

Keypad 0, ... ,9 

PERIOD 


Keypad period (.) 

Keypad period (.) 


COMMA 


Keypad comma (,) 

Keypad comma (,) 


MINUS 


Keypad minus (-) 

Keypad minus (-) 


ENTER 


ENTER 

ENTER 

ENTER 

El 


Find 



E2 


Insert Here 



E3 


Remove 



E4 


Select 



E5 


Prev Screen 



E6 


Next Screen 



HELP 


Help 



DO 


Do 



F6, F7, . . . 

, F20 

F6, F7.F20 




QUALIFIERS /ALL 

Displays all key definitions for the current state, by default, or for the states 
specified with the /STATE qualifier. When using /ALL, do not specify a key 
name. 

/BRIEF 

Displays only the key definitions (by default, all the qualifiers associated with 
a key definition are also shown, including any specified state) 
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SHOW KEY 


/DIRECTORY 

Displays the names of all the states for which keys have been defined. Do 
not specify other qualifiers with /DIRECTORY. 

/[NO]STATE=(state-name [, . . . ]) 

Selects one or more states for which a key definition is to be displayed. 
/STATE displays key definitions for the specified states. You may specify 
predefined key states, such as DEFAULT and GOLD, or user-defined states. 
A state name can be any appropriate alphanumeric string. /NOSTATE 
(default) displays key definitions for the current state only. 


DESCRIPTION Keypad mode must be enabled (SET MODE KEYPAD) before you can use 

this command. Keypad mode is enabled by default. 

By default, the current key state is the "DEFAULT" state. The current state 
may be changed with the SET KEY/STATE command, or by pressing a key 
that causes a state change (a key that was defined with the DEFINE/KEY 
/LOCK—STATE/STATE qualifier combination). 

Related commands: DEFINE/KEY, DELETE/KEY, SET KEY. 


EXAMPLES 

Q DBG> SHOW KEY/ALL 

This example shows how to display all the keys currently defined in the 
current state. 

g DBG> SHOW KEY/STATE=BLUE KP8 

GOLD keypad definitions: 

KP8 = "Scroll/Top" (noecho,terminate.nolock) 

This example shows how to display the definition for keypad key 8. 

0 DBG> SHOW KEY/BRIEF KP8 

DEFAULT keypad definitions: 

KP8 = "Scroll/Up" 

This example shows how to display the definition for keypad key 8 without 
any associated qualifiers or states. 

Q DBG> SHOW KEY/DIRECTORY 

MOVE.GOLD 
MOVE.BLUE 
MOVE 
GOLD 

EXPAND.GOLD 

EXPAND_BLUE 

EXPAND 

DEFAULT 

CONTRACT.GOLD 

CONTRACT.BLUE 

CONTRACT 

BLUE 


This command displays the names of the states for which keys have been 
defined. 
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SHOW LANGUAGE 


SHOW LANGUAGE 


Identifies the current language. 

FORMAT 

SHOW LANGUAGE 

PARAMETERS None. 

QUALIFIERS 

None. 

DESCRIPTION 

The current language is the language last established with the SET 
LANGUAGE command. If no SET LANGUAGE command was issued, 
the current language is, by default, the language established at debugger start 
up (the language of the module containing the transfer address). 

Related commands: SET LANGUAGE. 

EXAMPLE 


DBG> SHOW LANGUAGE 
language: BASIC 


This command displays the name of the current language as BASIC. 
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SHOW LOG 


SHOW LOG 

Identifies the current log file and reports whether the debugger is 
writing to that file. 

FORMAT 

SHOW LOG 

PARAMETERS 

None. 

QUALIFIERS 

None. 

DESCRIPTION 

The current log file is the log file last established by a SET LOG command. 

If no SET LOG command was issued, the current log file is the file 
SYS$DISK:[ ]DEBUG.LOG, by default. 

Related commands: SET LOG, SET OUTPUT [NO]LOG, SET OUTPUT 
[NO]SCREEN_LOG. 


EXAMPLES 


Q DBG> SHOW LOG 

not logging to DEBUG.LOG 

This command displays the name of the current log file as DEBUG.LOG (the 
default log file) and reports that the debugger is not writing to it. 

g DBG> SET LOG PR0G4 
DBG> SET OUTPUT LOG 
DBG> SHOW LOG 

logging to USER$:[JONES.WORK]PR0G4.LOG 

The SET LOG command establishes that the current log file is PROG4.LOG 
(in the current default directory). The SET OUTPUT LOG command 
causes the debugger to log debugger input and output into that file. The 
SHOW LOG command confirms that the debugger is writing to the log file 
PROG4.COM in the current default directory. 
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SHOW MARGINS 


SHOW MARGINS 


Displays the current source-line margin settings for the display of 
source code. 

FORMAT 

SHOW MARGINS 

PARAMETERS None. 

QUALIFIERS 

None. 

DESCRIPTION 

The current margin settings are the margin settings last established with the 
SET MARGINS command. If no SET MARGINS command was issued, the 
left margin is set to 1 and the right margin is set to 255 by default. 

Related commands: SET MARGINS. 


EXAMPLES 


Q DBG> SHOW MARGINS 

left margin: 1 , right margin: 255 

This command displays the default margin settings of 1 and 255. 

0 DBG> SET MARGINS 50 

DBG> SHOW MARGINS 
left margin: 1 , right margin: 50 

This command displays the default left margin setting of 1 and the modified 
right margin setting of 50. 

0 DBG> SET MARGINS 10:60 

DBG> SHOW MARGINS 

left margin: 10 . right margin: 60 


This command displays both margin settings modified to 10 and 60. 
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SHOW MAX—SOURCE—FILES 


SHOW MAX—SOURCE-FILES 

Displays the maximum number of source files that the debugger may 
keep open at any one time. 

FORMAT 

SHOW MAX_SOURCE_FILES 

PARAMETERS None. 

QUALIFIERS 

None. 

DESCRIPTION 

The maximum number of source files that the debugger may keep open 
at any one time may be specified using the SET MAX—SOURCE—FILES 
command. If no SET MAX—SOURCE—FILES command was issued, the 
maximum number of files is 5, by default. 

Related commands: SET MAX-SOURCE-FILES, (SET, SHOW, CANCEL) 
SOURCE. 

EXAMPLE 



DBG> SHOW MAX_SOURCE_FILES 
max_Bource_files: 7 


This command shows that the debugger may keep a maximum of 7 source 
files open at any one time. 
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SHOW MODE 


SHOW MODE 



Identifies the current debugger modes (screen or no screen, keypad 
or nokeypad, and so on) and the current radix. 

FORMAT 

SHOW MODE 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The current debugger modes are the modes last established with the SET 
MODE command. If no SET MODE command was issued, the current 
modes are, by default: DYNAMIC, NOG-FLOAT (d_float), KEYPAD, LINE, 
NOSCREEN, SCROLL, SYMBOLIC. 

Related commands: (SET, CANCEL) MODE, (SET, SHOW, CANCEL) 

RADIX. 


EXAMPLE 

DBG> SHOW MODE 

modes: symbolic, line, d_float, screen, scroll, keypad, dynamic 


input radix :decimal 
output radix:decimal 

The SHOW MODE command displays the current modes and current input 
and output radix. 











SHOW MODULE 


SHOW MODULE 


Displays information about one or more modules in your program. 


FORMAT SHOW MODULE [module-name] 


PARAMETERS module-name 

Specifies the name of a module to be included in the display. If you do 
not specify a name, or if you specify the wildcard character (*) by itself, all 
modules are listed. You can use * within a module name. Shareable image 
modules are selected only if the /SHARE qualifier is specified. 


QUALIFIERS /[NO]RELATED 

Note: /[NOJRELATED applies only to Ada programs. 

Controls whether the debugger includes, in the SHOW MODULE display, 
any module that is related to a specified module through a with-clause or 
subunit relationship. 

SHOW MODULE/RELATED displays related modules as well as those 
specified. The display identifies the exact relationship. By default ( 
/NORELATED), no related modules are selected for display (only the 
modules specified are selected). 

/[NOJSHARE 

Controls whether the debugger includes, in the SHOW MODULE display, 
any shareable image modules that have been linked with your program but 
are external to your program. These shareable images are primarily run-time 
library images, but they also include any shareable images called by your 
program. 

Dummy modules whose names have the prefix "SHARES" are created for 
each shareable image in your program. SHOW MODULE/SHARE displays 
these shareable image modules, as well as modules in the main image. By 
default (/NOSHARE) no shareable image modules are selected for display. 

Setting a shareable image module loads the universal symbols for that image 
into the run-time symbol table. Note that this feature overlaps the effect of 
the newer SET IMAGE and SHOW IMAGE commands. 


DESCRIPTION 





Note: The (SET, SHOW, CANCEL) MODULE commands operate on modules in 
the current image. This is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 
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SHOW MODULE 


The SHOW MODULE command displays the following information about 
one or more modules selected for display: 

• The module name 

• The language in which the module is written 

• Whether or not the symbol records of the module have been loaded into 
the debugger's run-time symbol table (RST) 

• The space (in bytes) required in the RST for symbol records in that 
module 

• The total number of modules selected in the display 

• The number of unused bytes in the space allocated for the RST 

Related commands: (SET, CANCEL) MODULE, (SET, SHOW, CANCEL) 
IMAGE, SET MODE [NO]DYNAMIC, SHOW SYMBOL, (SET, SHOW, 
CANCEL) SCOPE. 


EXAMPLE 


DBG> SHOW MODULE 
module name 

FOO,MAIN,SUB* 
symbols language 

size 

FOO 

yes 

MACRO 

432 

MAIN 

no 

FORTRAN 

280 

SUB1 

no 

FORTRAN 

164 

SUB 2 

no 

FORTRAN 

204 

total modules: 4 


remaining 

size: 60720 


The SHOW MODULE command displays information about the modules 
FOO and MAIN, and all modules having the prefix SUB. 
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SHOW OUTPUT 


SHOW OUTPUT 

Displays the current output options. 

FORMAT 

SHOW OUTPUT 

PARAMETERS 

None. 

QUALIFIERS 

None. 

DESCRIPTION 

The current output options are the options last established with the SET 
OUTPUT command. If no SET OUTPUT command was issued, the 
output options are, by default: NOLOG, NOSCREEN—LOG, TERMINAL, 
NOVERIFY. 

Related commands: SET OUTPUT, SET LOG, SET MODE SCREEN. 


EXAMPLE 


DBG> SHOW OUTPUT 

noverify, terminal, screen_log, logging to USER$:[JONES.WORK]DEBUG.LOG;9 

This command shows that the debugger is not displaying input command 
strings as it executes command procedures and commands in DO clauses; 
is displaying output on the terminal; is writing output to the log file 
USER$:[JONES.WORK]DEBUG.LOG;9; and is logging the screen contents 
as they are updated in screen mode. 
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SHOW RADIX 


SHOW RADIX 



Displays the current radix for the entry and display of integer data 
or, if the /OVERRIDE command qualifier is specified, the current 
override radix. 

FORMAT 

SHOW RADIX 


PARAMETERS None. 


QUALIFIERS 

/OVERRIDE 

Identifies the current override radix. 

DESCRIPTION 

The current radix for the entry and display of integer data is the radix last 
established with the SET RADIX command. If no SET RADIX command was 
issued, the radix for both input and output is hexadecimal for BLISS and 
MACRO and decimal for other languages. 

The current override radix for the display of all data is the override radix last 
established with the SET RADIX/OVERRIDE command. If no SET RADIX 
/OVERRIDE command was issued, the override radix is "none". 

Related commands: (SET, CANCEL) RADIX. 


EXAMPLES 

Q DBG> SHOW RADIX 

input radix: decimal 
output radix: decimal 

This command identifies the input radix and output radix as decimal. 

2 DBG> SET RADIX/OVERRIDE HEX 
DBG> SHOW RADIX/OVERRIDE 
output override radix: hexadecimal 

The SET RADIX/OVERRIDE command sets the override radix to hexadecimal 
and the SHOW RADIX/OVERRIDE command indicates the override radix. 
This means that all data will be displayed as hexadecimal integer data in 
commands such as EXAMINE and so on. 
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SHOW SCOPE 


SHOW SCOPE 



Displays the current scope search list for symbol lookup. 

FORMAT 

SHOW SCOPE 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The current scope search list designates one or more program locations 
(specified by path names and/or other special characters) to be used in the 
interpretation of symbols that are specified without path-name prefixes in 
debugger commands. 

The current scope search list is the scope search list last established with the 
SET SCOPE command. If no SET SCOPE command was issued, the current 
scope search list is 0,2,2, . . . ,N, by default. 

The default scope means that, for a symbol without a path-name prefix, a 
symbol lookup such as "EXAMINE X" first looks for X in the routine that is 
currently executing (scope 0); if no X is visible there, the debugger looks in 
the caller of that routine (scope 1), and so on down the call stack; if X is not 
found in scope N, the debugger searches the rest of the run-time symbol table 
(RST), then searches the global symbol table (GST), if necessary. 

If you have used a decimal integer in the SET SCOPE command to represent 
a routine in the call stack, the SHOW SCOPE command displays the name of 
the routine represented by the integer, if possible. 

Related commands: (SET, CANCEL) SCOPE. 


EXAMPLE 

DBG> SHOW SCOPE 

scope: MAIN. SUB1, 0[=SUB2],\ 

This example shows how to search for a symbol X (EXAMINE X) in MAIN, 
then in SUB1, then in the routine that contains the current PC, and finally 
globally. 
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SHOW SEARCH 


SHOW SEARCH 

Identifies the default qualifiers (/ALL or /NEXT, /IDENTIFIER or 
/STRING) currently in effect for the SEARCH command. 

FORMAT 

SHOW SEARCH 

PARAMETERS 

None. 

QUALIFIERS 

None. 

DESCRIPTION 

The default qualifiers for the SEARCH command are the default qualifiers last 
established with the SET SEARCH command. If no SET SEARCH command 
was issued, the default qualifiers are /NEXT and /STRING. 

Related commands: SET SEARCH, SEARCH, (SET, SHOW) LANGUAGE. 

EXAMPLE 



DBG> SHOW SEARCH 

search settings: search for next occurrence, as a string 
DBG> SET SEARCH IDENT 
DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> SET SEARCH ALL 
DBG> SHOW SEARCH 

search settings: search for all occurrences, as an identifier 

The first SHOW SEARCH command displays the default settings for the SET 
SEARCH command. By default, the debugger searches for and displays the 
next occurrence of the string. 

The second SHOW SEARCH command indicates that the debugger will 
search for the next occurrence of the string, but will only display the string if 
it is not bounded on either side by a character that can be part of an identifier 
in the current language. 

The third SHOW SEARCH command indicates that the debugger will search 
for all occurrences of the string, but will only display the strings if they are 
not bounded on either side by a character that can be part of an identifier in 
the current language. 
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SHOW SELECT 


SHOW SELECT 



Identifies the displays currently selected for each of the display 
attributes: error, input, instruction, output, program, prompt, scroll, 
and source. 

FORMAT 

SHOW SELECT 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The display attributes have the following properties: 

• A display that has the error attribute displays debugger diagnostic 
messages. 

• A display that has the input attribute echoes your debugger input. 

• A display that has the instruction attribute displays the decoded assembly 
language instruction stream of the routine being debugged. The display is 
updated when you enter an EXAMINE/INSTRUCTION command. 

• A display that has the output attribute displays any debugger output that 
is not directed to another display. 

• A display that has the program attribute displays program input and 
output. Currently only the PROMPT display can have the program 
attribute. 

• A display that has the prompt attribute is where the debugger prompts 
for input. Currently, only the PROMPT display can have the PROMPT 
attribute. 

• A display that has the scroll attribute is the default display for the 
SCROLL, MOVE, and EXPAND commands. 

• A display that has the source attribute displays the source code of the 
module being debugged, if available. The display is updated when you 
enter a TYPE or EXAMINE/SOURCE command. 

Related commands: SELECT, SHOW DISPLAY. 


CD-I 70 











SHOW SELECT 


EXAMPLE 


DBG> SHOW SELECT 
display selections: 
scroll = SRC 
input = none 
output = OUT 
error = PROMPT 
source = SRC 
instruction = none 
program - PROMPT 
prompt = PROMPT 


The SHOW SELECT command identifies the displays currently selected for 
each of the display attributes. The display selections shown are the default 
selections for all languages except MACRO. 
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SHOW SOURCE 


SHOW SOURCE 



Displays the source directory search lists currently in effect. 

FORMAT 

SHOW SOURCE 


PARAMETERS None. 


QUALIFIERS /EDIT 

Note: /EDIT applies mainly to Ada programs, 



Identifies the search list for source files to be edited when you use the EDIT 
command. 

DESCRIPTION 

If a source directory search list has not been established by means of the SET 
SOURCE or SET SOURCE/MODULE=module-name commands, the SHOW 
SOURCE command indicates that no directory search list is currently in effect. 
In this case, the debugger expects each source file to be in the same directory 
that it was in at compile time (the debugger also checks that the creation date 
and time of a source file match the information in the debugger's symbol 
table). 

The SET SOURCE/MODULE=module-name command establishes a source 
directory search list for a particular module. The SET SOURCE command 
establishes a source directory search list for all modules not explicitly 
mentioned in a SET SOURCE/MODULE=module-name command. When 
those commands have been used, the SHOW SOURCE command identifies 
the source directory search list associated with each search categories. 

The /EDIT qualifier is needed when the files used for the display of source 
code are different from the files to be edited by means of the EDIT command. 
This is the case with Ada programs. For Ada programs, the SHOW SOURCE 
command identifies the search list of files used for source display (the "copied" 
source files in Ada program libraries); the SHOW SOURCE/EDIT command 
identifies the search list for the source files you edit when using the EDIT 
command. 

Related commands: (SET, CANCEL) SOURCE, (SET, SHOW) MAX_ 
SOURCE—FILES. 
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SHOW SOURCE 


EXAMPLES 

Q DBG> SHOW SOURCE 

no directory search list in effect 

DBG> SET SOURCE [PROJA],[PROJB].DISK:[PETER.PROJC] 

DBG> SHOW SOURCE 

source directory search list for all modules: 

[PROJA] 

[PROJB] 

DISK:[PETER.PROJC] 

This example shows how the SET SOURCE command tells the debugger to 
search the directories [PROJA],[PROJB], and DISK:[PETER.PROJC]. 

2 DBG> SET SOURCE/MODULE=COBOLTEST DISK$2:[PROJD].[014,015] 

DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 

DISK$2: [PROJD] 

[014,015] 

source directory search list for all other modules: 

[PROJA] 

[PROJB] 

DISK:[PETER.PROJC] 

This example shows how the SET SOURCE command tells the debugger to 
search the directories DEVICE:[PROJD] and [014,015]) for source files to use 
with the module COBOLTEST. 
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SHOW STACK 


Displays information from the current call stack. 

FORMAT 

SHOW STACK [n] 

PARAMETERS 

n 

Specifies the number of frames to display. If n is omitted, information about 
all stack frames is displayed. 

QUALIFIERS 

None. 

DESCRIPTION 

For each call frame, the SHOW STACK command displays information such 
as the condition handler, saved register values, and the argument list, if any. 
The latter is the list of arguments passed to the subroutine with that call. In 
some cases the argument list may contain the addresses of actual arguments. 
In such cases, "DBG> EXAMINE address" will return the values of these 
arguments. 

Related commands: SHOW CALLS. 


EXAMPLES 


Q DBG> SHOW STACK 

stack frame 0 (2146814812) 


condition handler: 

0 

SPA: 

0 

S: 

0 

mask: 

~M<R2> 

PSW: 

0000 (hexadecimal) 

saved AP: 

7 

saved FP: 

2146814852 

saved PC: 

EIGHTQUEENS 

saved R2: 

0 

argument list:(l) 

EIGHTQUEENS 


stack frame 1 (2146814852) 

condition handler: SHARE$PASRTL+888 


SPA: 

0 

S: 

0 

mask: 

none saved 

PSW: 

0000 (hexadecimal) 

saved AP: 

2146814924 

saved FP: 

2146814904 

saved PC: 

SHARE$DEBUG+667 


The SHOW STACK command displays information about all stack frames at 
the current PC location. 
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SHOW STEP 


SHOW STEP 

Identifies the default qualifiers (/INTO, /INSTRUCTION, /NOSILENT 
and so on) currently in effect for the STEP command. 

FORMAT 

SHOW STEP 

PARAMETERS None. 

QUALIFIERS 

None. 

DESCRIPTION 

The default qualifiers for the STEP command are the default qualifiers last 
established by the SET STEP command. If no SET STEP command was 
issued, the default qualifiers are those established by the current language. 

Related commands: SET STEP, STEP, (SET, SHOW) LANGUAGE. 

EXAMPLE 



DBG> SET STEP INTO,NOSYSTEM,NOSHARE,INSTRUCTION,NOSOURCE 
DBG SHOW STEP 

step type: nosystem, noshare, nosource, nosilent, into routine calls, by instruction 

This SHOW STEP command indicates that the debugger will: 

• Step into called routines, but not those in system space or in shareable 
images 

• Step by instruction 

• Not display lines of source code while stepping 
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SHOW SYMBOL 


SHOW SYMBOL 



Displays symbols in the debugger's run-time symbol table. 

FORMAT 

SHOW SYMBOL symbol-name[\N scope[, ... 77 
[,symbol-name [IN scope[, ... 77 


PARAMETERS symbol-name 

Specifies a symbol to be identified. A valid symbol name is a single identifier 



or a label name of the form %LABEL n, where n is an integer. Compound 
names such as RECORD.FIELD or ARRAY[1,2] are not valid. If you specify 
the wildcard character (*) by itself, all symbols are listed. You can use * 
within a display name. 

scope 

Specifies the name of a module, routine, or lexical block, or a numeric scope. 

It has the same syntax as the scope specification in a SET SCOPE command 
and may include path-name qualification. All specified scopes must be in set 
modules. 

The SHOW SYMBOL command displays only those symbols in the RST that 
both match the specified name and are declared within the lexical entity 
specified by the scope parameter. If the scope parameter is omitted, all set 
modules and the GST (global symbol table) are searched for symbols that 
match the name specified by the namespec parameter. 

QUALIFIERS 

/ADDRESS 

Displays the address specification for each selected symbol. The address 
specification is the method of computing the symbol's address. It may 
merely be the symbol's virtual address, but it may also involve indirection or 
an offset from a register value. Some symbols have address specifications 
too complicated to present in any understandable way. These address 
specifications are labeled "complex address specifications." 

/DEFINED 

Displays symbols you have defined with the DEFINE command. 

/DIRECT 

Displays only those symbols that are declared directly in the scope parameter. 
Symbols declared in lexical entities nested within the scope specified by the 
scope parameters will not be shown. 

/LOCAL 

Displays symbols that are defined with the DEFINE/LOCAL command. 

/TYPE 

Displays data type information for each selected symbol. 
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SHOW SYMBOL 


/USE-CLAUSE 

Note: /USE—CLAUSE applies only to Ada programs. 

Identifies any Ada package that a specified block, subprogram, or package 
names in a use clause. If the symbol specified is a package, also identifies 
any block, subprogram, package, and so on that names the specified symbol 
in a use clause. 


DESCRIPTION The SHOW SYMBOL command displays information that the debugger has 

about a given symbol. This information may not be the same as what the 
compiler had or even what you see in your source code. Nonetheless, it is 
useful for understanding why the debugger may act as it does when handling 
symbols. 

Related commands: DEFINE, SYMBOLIZE. 


EXAMPLES 

Q DBG> SHOW SYMBOL I 
data FORARRAYXI 

This command shows that symbol I is located in module FORARRAY. 

g DBG> SHOW SYMBOL INTARRAY1 
data FORARRAY\INTARRAY1 

This command shows that symbol INTARRAY1 is located in module 

FORARRAY. 

0 DBG> SHOW SYMBOL/ADDRESS INTARRAY1 
data F0RARRAYXINTARRAY1 

descriptor address: 0009DE8B 

This command shows that symbol INTARRAY1 is located in module 

FORARRAY and has a virtual address of 0009DE8B. 

2 DBG> SHOW SYMBOL *tarr* 
data FORARRAYXINTARRAY1 
data F0RARRAYXINTARRAY2 
data FORARRAYXINTARRAY3 

This command displays all the symbol names containing the string "tarr" and 

their locations in module FORARRAY. 

0 DBG> SHOW SYMBOL/TYPE/ADDRESS * 

This command displays all information about all symbols. 

0 DBG> DEFINE/COMMAND SB=SET BREAK 
dbg> show SYMBOL/DEFINED SB 
defined SB 

bound to: SET BREAK 
was defined /command 


The DEFINE/COMMAND command defines SB as a symbol for the 
command SET BREAK. The SHOW SYMBOL/DEFINED command displays 
that definition. 
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SHOW TASK 


SHOW TASK 


Displays information about the tasks of a tasking program. 

Note: The SHOW TASK command currently applies only to Ada programs. See 
the VAX Ada documentation for complete information. 


FORMAT SHOW TASK [ task-expression ^, . . . ]] 


PARAMETERS task-expression 

Specifies a task value. A task expression may be: 

• An Ada language expression for a task value—for example, a task object 
name. You can use a path name. 

• The task ID (for example, %TASK 2), as indicated in a SHOW TASK 
display. 

• A pseudo-task name (% ACTIVE _TASK, % CALLER—TASK, %NEXT_ 
TASK, or % VISIBLE-TASK). 

Do not use the wildcard character (*). See the qualifier descriptions for 
details on how to specify tasks with particular qualifiers. 


QUALIFIERS /ALL 

Selects all tasks that currently exist in the program for display. Do not specify 
a task with /ALL. 

/CALLS[=n] 

Performs a SHOW CALLS command for each task selected for display. You 
can use the SHOW CALLS command to obtain the current PC of a task. 

/FULL 

Displays additional information about each task selected for display. /FULL 
provides additional information if used either by itself, or with the /CALLS 
or /STATISTICS qualifier. 

/[I\IOJHOLD 

Selects either tasks that are on HOLD, or tasks that are not on HOLD for 
display. 

If you do not specify a task, /HOLD selects all tasks that are on HOLD. If 
you specify a task list, /HOLD selects the tasks in the task list that are on 
HOLD. 

If you do not specify a task, /NOHOLD selects all tasks that are not on 
HOLD. If you specify a task list, /NOHOLD selects the tasks in the task list 
that are not on HOLD. 
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SHOW TASK 


/PRIORITY=(n[, . . . ]) 

If you do not specify a task, selects all tasks that have any of the specified 
priorities, n, where n is a decimal integer from 0 to 15 inclusive. If you 
specify a task list, selects the tasks in the task list that have any of the 
priorities specified. 

/STATE=(state[, . . . ]) 

If you do not specify a task, selects all tasks that are in any of the specified 
states (the possible states are RUNNING, READY, SUSPENDED, or 
TERMINATED). If you specify a task list, selects the tasks in the task list 
that are in any of the states specified. 

/STATISTICS 

Displays tasking statistics for the entire tasking system. You can use this 
information to measure the performance of your tasking program. The larger 
the number of total schedulings (also known as context switches), the more 
tasking overhead there is. When you specify /STATISTICS, the only other 
permissible qualifier is /FULL. 

/TIME-SLICE 

Displays the current value of pragma TIME—SLICE. 


DESCRIPTION You can select tasks for display with the SHOW TASK command by 

specifying any of the following: 

• A task list—that is, a list of task expressions. 

• Task selection qualifiers: /ALL, /[NOJHOLD, /PRIORITY, /STATE. 

• Both a task list and task selection qualifiers. Only the tasks that satisfy all 
specified criteria are selected for display. 

If no task parameters or task selection qualifiers are given, the SHOW TASK 
command displays summary information about the visible task. 

Related commands: SET TASK, SET BREAK/EVENT, SET TRACE/EVENT, 
EXAMINE/TASK, DEPOSIT/TASK. 


EXAMPLES 


Q DBG> SHOW TASK/ALL 

task id pri hold state substate 

* ‘/.TASK 1 7 RUN 

•/.TASK 2 7 HOLD SUSP Accept 

7.TASK 3 6 READY Entry call 


task object 
122624 

TASK.EXAMPLE.MONITOR 
TASK.EXAMPLE.CHECK.IN 


The SHOW TASK/ALL command provides basic information on all the tasks 
of a program that are currently in existence—namely, tasks that have been 
created and whose master has not yet terminated. One line is devoted to 
each task. The active task is marked with an asterisk and is always the task 
that is in the RUN state. 


0 DBG> SHOW TASK %ACTIVE_TASK,'/.TASK 3,MONITOR 


This command selects the active task, %TASK 3, and task MONITOR for 
display. 
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E DBG> SHOW TASK/PRI0RITY=6 

This command selects all tasks with priority 6 for display. 

E DBG> SHOW TASK/STATE*(RUN,SUSP) 

This command selects all tasks that are either running or suspended for 
display. 

E DBG> SHOW TASK/STATE=SUSP/NOHOLD 

This command selects all tasks that are both suspended and not on hold for 
display. 

E DBG> SHOW TASK/STATE*(RUN,SUSP)/PRI0*7 %VISIBLE_TASK,y,TASK 3 

This command selects for display those tasks among the visible task and 
%TASK 3 that are in either the RUNNING or SUSPENDED STATE, and have 
priority 7. 
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SHOW TERMINAL 


SHOW TERMINAL 



Displays the current terminal screen height (page) and width being 
used to format output. 

FORMAT 

SHOW TERMINAL 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The current terminal screen height and width are the height and width 
last established by the SET TERMINAL command. If no SET TERMINAL 
command was issued, the current height and width are, by default, the height 
and width known to the VAX/VMS terminal driver, as displayed by the DCL 
command SHOW TERMINAL (usually 24 lines and 80 columns, respectively, 
for VT-series terminals). 

Related commands: SET TERMINAL, SHOW DISPLAY, SHOW WINDOW. 

EXAMPLE 


DBG> SHOW TERMINAL 
terminal width: 80 
page: 24 

This command displays the current terminal screen width and height (page) 
as 80 columns and 24 lines, respectively. 
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SHOW TRACE 


SHOW TRACE 



Displays information about all tracepoints established by the SET 
TRACE command, including WHEN and DO clauses and /AFTER 
counts. 

FORMAT 

SHOW TRACE 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The debugger displays all information about each tracepoint that is currently 
set, including any optional WHEN and DO clauses. 

If you established a tracepoint using the /AFTER:n command qualifier with 
the SET TRACE command, the SHOW TRACE command displays the current 
value of the decimal integer n, that is, the originally specified integer value 
minus one for each time the tracepoint location was reached. (The debugger 
decrements n each time the tracepoint location is reached until the value of n 
is zero, at which time the debugger takes trace action.) 

Related commands: (SET, CANCEL) TRACE. 


EXAMPLE 

DBG> SHOW TRACE 
tracepoint at CALC\MULT 

tracing /CALL instructions: CALLS, CALLG, BSBW, BSBB, JSB, RSB 


and RET 

When the debugger encounters routine MULT in module CALC, or one of the 
instructions CALLS, CALLG, BSBW, BSBB, JSB, RSB, or RET, it will suspend 
program execution, report a message announcing its arrival at the tracepoint, 
and resume program execution. 


CD-182 









SHOW TYPE 


SHOW TYPE 



Displays the current type for program locations that do not have a 
compiler-generated type or, if the /OVERRIDE command qualifier is 
specified, the current override type. 

FORMAT 

SHOW TYPE 


PARAMETERS None. 


QUALIFIERS 

/OVERRIDE 

Identifies the current override type. 

DESCRIPTION 

The current type for program locations that do not have a compiler-generated 
type is the type last established by the SET TYPE command. If no SET TYPE 
command was issued, the type for those locations is longword integer. 

The current override type for all program locations is the override type 
last established by the SET TYPE/OVERRIDE command. If no SET TYPE 
/OVERRIDE command was issued, the override type is "none". 

Related commands: SET TYPE, CANCEL TYPE/OVERRIDE. 


EXAMPLES 

Q DBG> SET TYPE QUADWORD 

dbg> show type 

type: quadword integer 

The SET TYPE command sets the type for locations that do not have a 
compiler generated type to quadword. The SHOW TYPE command displays 
the current default type for those locations as quadword integer. This means 
that the debugger will interpret and display entities at those locations as 
quadword integers unless you specify otherwise (for example with a type 
qualifier on the EXAMINE command). 

Q DBG> SHOW TYPE/OVERRIDE 
type/override: none 

This command indicates that no override type has been defined. 
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SHOW WATCH 



Displays information about all watchpoints established by the SET 
WATCH command, including WHEN and DO clauses and /AFTER 
counts. 

FORMAT 

SHOW WATCH 


PARAMETERS None. 


QUALIFIERS 

None. 

DESCRIPTION 

The debugger displays all information about each watchpoint that is currently 
set, including any optional WHEN and DO clauses. 

If you established a watchpoint using the /AFTER:n command qualifier with 
the SET WATCH command, the SHOW WATCH command displays the 
current value of the decimal integer n, that is, the originally specified integer 
value minus one for each time the watchpoint location was reached. (The 
debugger decrements n each time the watchpoint location is reached until the 
value of n is zero, at which time the debugger takes watch action.) 

Related commands: (SET, CANCEL) WATCH. 


EXAMPLE 

DBG> SHOW WATCH 
watchpoint of MAIN\ALPHA 
watchpoint of SUB2\TABLE+20 

This command displays two watchpoints, one at location MAIN\ALPHA and 
the other at location SUB2\TABLE+20. 
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SHOW WINDOW 


SHOW WINDOW 


Displays the name and screen position of predefined and user- 
defined windows. 

FORMAT 

SHOW WINDOW [wname[, . . . ]] 

PARAMETERS 

vjname 

Specifies the name of a window. If you do not specify a name, or if you 
specify the wildcard character (*) by itself, all window definitions are listed. 
You can use * within a window name. When using /ALL, do not specify a 
window name. 

QUALIFIERS 

/ALL 

Lists all window definitions. Do not specify a window definition name with 
/ALL. 

DESCRIPTION 

Related commands: (SET, CANCEL) WINDOW, (SET, SHOW, CANCEL) 
DISPLAY, SHOW SELECT, (SET, SHOW) TERMINAL. 


EXAMPLE 


dbg> show window lh*,rh* 

window LH1 at (1,11,1,40) 
window LH12 at (1,23,1,40) 
window LH2 at (13,11,1,40) 
window RH1 at (1,11,42,39) 
window RH12 at (1,23,42,39) 
window RH2 at (13,11,42,39) 


This command displays the name and screen position of all screen window 
definitions whose names starts with LH or RH. 


CD-185 













SPAWN 


SPAWN 

Lets you execute DCL commands without terminating a debugging 
session or losing the current debugging context. 

FORMAT 

SPAWN [dcl-command] 


PARAMETERS dcl-command 

Specifies a DCL command. If you specify a DCL command, the command is 
executed in a subprocess. Control is returned to the debugging session when 
the DCL command terminates. 

If you do not specify a DCL command, a subprocess is created and you can 
then enter DCL commands. Either logging out of the spawned process or 
attaching to the parent process (with the DCL ATTACH comand) will allow 
you to continue your debugging session. 

If the DCL command contains a semicolon, you must enclose the command 
in quotation marks. Otherwise the semicolon is interpreted as a debugger 
command separator. To include a quotation mark inside the string, enter two 
consecutive quotation marks. 


QUALIFIERS 

/NOWAIT 

Executes the subprocess in parallel with the debugging session. You can issue 
debugger commands while the subprocess is running. If you use /NOWAIT, 
you should specify a DCL command with the SPAWN command; the DCL 
command is executed in the subprocess. 

DESCRIPTION 

The SPAWN command acts exactly like the DCL SPAWN command. You 
can edit files, compile programs, read mail, and so on without ending your 
debugging session or losing your current debugging context. 

In addition, you can spawn a DCL SPAWN command. DCL picks up the 
second SPAWN command and interprets the qualifier. 

Related commands: ATTACH. 


EXAMPLES 


Q DBG> SPAWN 

$ 


The SPAWN command with no parameter specified spawns a subprocess at 
DCL level. You can now enter DCL commands. Log out to return to the 
debugger prompt. 


CD-186 










SPAWN 


0 DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG OMYCOM 
DBG> 


The SPAWN/NOWAIT command spawns a subprocess that is executed in 
parallel with the debugging session. This subprocess spawns the execution of 
the command procedure MYCOM.COM. The output from that operation is 
written to the file MYCOM.LOG. 
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STEP 

Causes the debugger to execute your program by line, by 
instruction, or by some other step unit. The step behavior depends 
on the step mode previously established by a SET STEP command 
and on the qualifier used with the STEP command. 

FORMAT 

STEP [n] 


PARAMETERS n 

Specifies the number of lines or instructions to be executed by the STEP 



command. If you do not specify the parameter n, the debugger executes one 
line or one instruction. The parameter n is always interpreted as a decimal 
integer. 

QUALIFIERS 

/BRANCH 

Causes the debugger to step to the next branch instruction. STEP/BRANCH 
does the same as SET BREAK/BRANCH;GO except that it does not create a 
permanent breakpoint. 

/CALL 

Causes the debugger to step to the next call or return instruction. STEP 
/CALL does the same as SET BREAK/CALL;GO except that it does not 
create a permanent breakpoint. 

/EXCEPTION 

Causes the debugger to step to the next exception condition. STEP 
/EXCEPTION does the same as SET BREAK/EXCEPTION;GO except that it 
does not create a permanent breakpoint. 

/INSTRUCTION 

Causes the debugger to step a single machine instruction. STEP 
/INSTRUCTION does the same as SET BREAK/TEMPORARY 
/INSTRUCTION;GO. This is the default behavior for language MACRO. 


/INSTRUCTION=(opcode[, . . . ]) 

Causes the debugger to step to the next machine instruction whose opcode is 
specified in the list. STEP/INSTRUCTION=(opcode[, . . . ]) does the same as 
SET BREAK/TEMPORARY/INSTRUCTION=(opcode[, . . . ]);GO. 

/INTO 

If you are at a call to a routine, causes the debugger to step into that routine. 
Otherwise, has the same effect as STEP without a qualifier. 
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The STEP/INTO behavior may be qualified as follows: 

• If SET STEP NOJSB was previously specified, or if you specify STEP 
/INTO/NOJSB, you step over a routine that was called by a JSB 
instruction (see the description of the /OVER qualifier). 

• If SET STEP NOSHARE was previously specified, or if you specify STEP 
/INTO/NOSHARE, you step over a routine that is in a shareable image. 

• If SET STEP NOSYSTEM was previously specified, or if you specify STEP 
/INTO/NOSYSTEM you step over a routine that is in system (PI) space. 

/[NO]JSB 

/[NO]JSB qualifies a previous SET STEP INTO command or a current STEP 
/INTO command. If you are at a routine call, /JSB lets the debugger step into 
the routine, whether it is called by a CALL instruction or by a JSB instruction. 
This is the default for all languages except DIBOL. /NOJSB lets the debugger 
step into a routine called by a CALL instruction but causes the debugger to 
step over a routine called by a JSB instruction (see description of /OVER 
qualifier). In DIBOL, user-written routines are called by the CALL instruction 
and DIBOL run-time library routines are called by the JSB instruction. 

/LINE 

Causes the debugger to step to the next line of your program. This is the 
default behavior for all languages except MACRO. 

/OVER 

If you are at a call to a routine, causes the debugger to step over the routine. 
The routine is executed. However, any code executed in the routine, up to 
and including the corresponding RETURN instruction, is considered part of a 
single STEP. This is the default behavior. 

/RETURN 

Causes the debugger to step to the return instruction of the routine you are 
now in. Thus, STEP/RETURN n will take you up n levels of the call stack.) 

/[NOJSHARE 

/[NOJSHARE qualifies a previous SET STEP INTO command or a current 
STEP/INTO command. If you are at a call to a shareable image routine, 
/SHARE lets the debugger step into that routine. This is the default. 
/NOSHARE causes the debugger to step over that shareable image routine 
(see description of /OVER qualifier). 

/[NOJSILENT 

Controls whether the "stepped to ... " message and other output associated 
with the STEP command is displayed. /SILENT specifies that no message or 
other output be displayed. /NOSILENT is the default and specifies that the 
step message and other output be displayed. 

/[NOJSOURCE 

Controls whether the source code corresponding to the current program 
location is displayed after the STEP command is executed. /SOURCE is the 
default and specifies that source code be displayed. /NOSOURCE specifies 
that no source code be displayed. 
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/[.NOJSYSTEM 

/[NO]SYSTEM qualifies a previous SET STEP INTO command or a current 
STEP/INTO command. If you are at a call to a system routine (in PI space), 
/SYSTEM lets the debugger step into that routine. This is the default. 
/NOSYSTEM causes the debugger to step over that system routine (see 
description of /OVER qualifier). 


DESCRIPTION STEP command qualifiers determine the exact stepping behavior. In general, 

when you issue a STEP command, the debugger takes the following action: 

1 Executes an instruction or a set of instructions. 

2 Reports the instruction or line that follows the last instruction executed. 

3 Reports the source line corresponding to the line or instruction that 
follows the last instruction executed (but only if the SOURCE parameter 
is in effect by virtue of STEP/SOURCE or SET STEP SOURCE and source 
lines are available). 

4 Issues the DBG> prompt. 

The following qualifiers affect the location to which you step: 

/BRANCH 

/CALL 

/EXCEPTION 

/INSTRUCTION 

/INSTRUCTION=(opcode-list) 

/LINE 

/RETURN 

The following qualifiers affect what output is seen on a step: 

/[NO]SILENT 

/[NO]SOURCE 

The following qualifiers affect what happens at a routine call: 

/INTO 

/[NO]JSB 

/OVER 

/[NO]SHARE 

/[NOJSYSTEM 

Each language establishes default STEP conditions (use the SHOW STEP 
command to identify these). If you plan to issue several STEP commands 
with the same qualifiers, you can first use the SET STEP command to 
establish new default qualifiers (for example, SET STEP INTO NOSYSTEM 
makes the STEP command behave like STEP/INTO/NOSYSTEM). Then 
you do not have to use those qualifiers with the STEP command. You can 
override the current default qualifiers for the duration of a single STEP 
command by specifying other qualifiers. 

Related commands: (SET, SHOW) STEP, GO, (SET, SHOW) LANGUAGE. 
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STEP 


EXAMPLES 

Q DBG> STEP 

stepped to FORSQUARE$MAIN\*/.LINE 4 

4: OPEN(UNIT=8, FILE=’DATAFILE.DAT’, STATUS=’OLD *) 

This command tells the debugger to execute the next line (by default). The 
PC is then positioned at the beginning of line 4. 

E DBG> STEP/INSTRUCTION 

stepped to MAIN\MAIN+14: MOVL 222,RO 

This command tells the debugger to execute the next instruction. The PC is 
then positioned at instruction MOVL, located at MAIN\MAIN+14. 

E DBG> STEP/INTO 

stepped to routine SUBi: MOVAL L~0000060C,R11 

This command tells the debugger to step into the routine that is being called 
at the current PC location. The PC is then positioned at routine SUBI. 
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SYMBOLIZE 



Converts a virtual address to a symbolic representation. 

FORMAT 

SYMBOLIZE address-expressionf, ... 7 


PARAMETERS address-expression 

Specifies an address expression to be symbolized. Do not use the wildcard 



character (*). 

QUALIFIERS 

None. 

DESCRIPTION 

If the address is a static address, it is symbolized as the nearest preceding 
symbol name, plus an offset. If the address is also a code address, the line 
number is included in the symbolization if a line number can be found that 
covers the address. 

If the address is a register address, the debugger displays all symbols in all 
SET modules that are bound to that register. The full path name of each such 
symbol is displayed. The register name itself ("%R5," for example) is also 
displayed. 

If the address is a stack location in the call frame of a routine in a SET 
module, the debugger searches for all symbols in that routine whose 
addresses are relative to the Frame Pointer (FP) or the Stack Pointer (SP). 

The closest preceding symbol name plus an offset is displayed as the 
symbolization of the address. A symbol whose address specification is 
too complex is ignored. 

If the debugger can find no symbolization for the address, a message is 
displayed. 

Related commands: SET MODE [NO]SYMBOLIC, SET MODE [NO]LINE. 


EXAMPLE 


DBG> SYMBOLIZE %R5 
address PR0GV/.R5: 

PROG\X 

This example shows that the local variable X in routine PROG is located in 
register R5. 
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TYPE 

Displays lines of source code. 

FORMAT 

TYPE [[mod-nam\]lin-num[:lin-num] 

[,[mod-nam\]lin-num[:lin-num][, . . . ]] 


PARAMETERS mod-nam 

Specifies the module that contains the source lines to be displayed. If you 



specify a module name along with the line numbers, use standard path-name 
notation: insert a backslash (\) between the module name and the line 
numbers. 

If you do not specify a module name, the debugger uses the current scope 
search list (as established by a previous SET SCOPE command, or the default 
scope search list 0,1, ... ,N if no SET SCOPE command was issued) to 
find source lines for display. The debugger looks for the source lines of the 
module associated with each successive scope region in the search list until 
source lines are found. 

lin-num 

Specifies a compiler-generated line number (a number used to label a source 
language statement or statements). 

If you specify a single line number, the debugger displays the source code 
corresponding to that line number. 

If you specify a list of line numbers, separating each with a comma, the 
debugger displays the source code corresponding to each of the line numbers. 

If you specify a range of line numbers, separating the starting and ending line 
numbers in the range with a colon, the debugger displays the source code 
corresponding to that range of line numbers. 

You can read through all the source language statements in your program by 
specifying a range of line numbers starting from 1 and ending at a number 
equal to or greater than the largest line number in the program listing. 

QUALIFIERS 

None. 

DESCRIPTION 

The TYPE command displays the lines of source code that correspond to the 
specified line numbers. The line numbers used by the debugger to identify 
lines of source code are generated by the compiler and appear in the compiler 
listing. 

After displaying a single line of source code, you can display the next line by 
issuing a TYPE command without a line number, that is, by issuing a TYPE 
command and then pressing the RETURN key. You can then display the next 
line and successive lines by repeating this sequence, in effect, reading through 
your source program one line at a time. 
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TYPE 



Related commands: SET MODE [NOJSCREEN, EXAMINE/SOURCE, SET 
STEP [NOJSOURCE, STEP/[NO]SOURCE, SET (BREAK, TRACE, WATCH) 
/[NOJSOURCE. 


EXAMPLES 


Q DBG> TYPE 160 

module C0B0LTEST 

160: START-IT-PARA. 

DBG> TYPE 
module COBOLTEST 

161: MOVE SCI TO ESO. 


a 


DBG> TYPE 160:163 


The first TYPE command displays line 160 of the source code and the second 
TYPE command displays the next line. 


module COBOLTEST 

160: START-IT-PARA. 

161: MOVE SCI TO ESO. 

162: DISPLAY ESO. 

163: MOVE SCI TO ESI. 


E 


This command displays lines 160 through 163 of the source code. 


DBG> TYPE COBOLTEST\160,22:24 
module COBOLTEST 

160: START-IT-PARA. 
module COBOLTEST 

22: 02 SC2V2 PIC S99V99 

23: 02 SC2V2N PIC S99V99 

24: 02 CPP2 PIC PP99 



COMP VALUE 22.33. 
COMP VALUE -22.33. 
COMP VALUE 0.0012 


This command displays lines 160 and lines 22 through 24 in the module 
COBOLTEST. 
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UNDEFINE 


UNDEFINE 


The UNDEFINE command is identical to the DELETE command. See 
the description of the DELETE command. 
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UNDEFINE/KEY 


The UNDEFINE/KEY command is identical to the DELETE/KEY 
command. See the description of the DELETE/KEY command. 


CD-196 









WHILE 


WHILE 

Executes a sequence of commands conditionally. 

FORMAT 

WHILE boolean-expression DO (command[; . . . ]) 


PARAMETERS boolean-expression 

Specifies a language expression that evaluates as a Boolean value (TRUE or 



FALSE) in the currently set language. 

command 

Specifies a debugger command. If you specify more than one command, 
separate them with semicolons. 

QUALIFIERS 

None. 

DESCRIPTION 

The WHILE command evaluates a boolean expression in the current language. 
If the value is TRUE, the command list in the DO clause is executed. The 
command then repeats the sequence, reevaluating the boolean-expression and 
executing the command-list until the expression is evaluated as FALSE. 

If the boolean-expression is FALSE, the WHILE command terminates. 

Related commands: FOR, REPEAT, EXITLOOP. 


EXAMPLE 

DBG> WHILE (X.EQ.O) DO (STEP/SILENT) 

This command tells the debugger to keep stepping through the program until 
X no longer equals 0 (FORTRAN example). 
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Command Defaults 


This appendix identifies the defaults associated with debugger commands. 


Command 

Default 

@file-spec 

For any field of the file specification that is not 
specified, the default is SYS$DISK:[]DEBUG.COM. 
This may be changed with a SET ATSIGN 
command. 

CALL 

Arguments are passed by address (%ADDR). 

DEFINE 

DEFINE/ADDRESS 

DEFINE/KEY 

DEFINE/KEY/ECHO/NOIF_ST ATE/NOLOCK_ 

ST ATE/LOG/NOSET_ST ATE/NOTERMIN ATE 

DELETE/KEY 

DEPOSIT 

DELETE/KEY/LOG/NOSTATE 

Language expressions and address expressions are 
interpreted according to the currently set language. 

DISPLAY 

DISPLAY/D YNAMIC/NOMARK_CHANGE/POP. 

The current display kind, window, and size remain 
unchanged. 

EDIT 

EDIT/NOEXIT. The default is to SPAWN the VAX 
Language Sensitive Editor. This may be changed 
with a SET EDITOR command. The default source 
file to be edited is the file whose source code 
appears in the current source display. The default 
position of the editing cursor is either the start 
of the line that is centered in the current source 
display, or the start of line 1 if the editor was set 
to /NOSTART_POSITION. 

ENABLE (DISABLE) AST 

EVALUATE 

ENABLE AST 

Language expressions are interpreted according to 
the currently set language. 

EXAMINE 

Address expressions are interpreted according to 
the currently set language. 

EXPAND 

EXPAND/DOWN, /UP: 1 line. EXPAND/LEFT, 
RIGHT: 1 column. 

EXTRACT 

If you specify /SCREEN—LAYOUT, the 
default specification for the output file is 
SYS$DISK:[JDBGSCREEN.COM. Otherwise, 
the default specification for the output file is 
SYS$DISK:[ JDEBUG.TXT. 

MOVE 

MOVE/DOWN, /UP: 1 line. MOVE/LEFT, RIGHT: 1 
column. 

SCROLL 

SCROLL/DOWN, /UP: 3/4 of window height. 
SCROLL/LEFT, /RIGHT: 8 columns. 

SEARCH 

SEARCH/NEXT/STRING 
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Command Defaults 


Command 


Default 


SELECT 
SET ATSIGN 
SET BREAK 

SET DEFINE 
SET DISPLAY 


SET EDITOR 
SET IMAGE 
SET KEY 
SET LANGUAGE 

SET LOG 
SET MARGINS 

SET MAX—SOURCE_FILES 
SET MODE 

SET OUTPUT 

SET PROMPT 
SET RADIX 

SET SCOPE 


SET SEARCH 
SET SOURCE 

SET STEP 

SET TERMINAL 

SET TRACE 


SELECT/SCROLL 

SET ATSIGN SYS$DISK:[]DEBUG.COM 

SET BREAK/INTO/JSB/SHARE/SYSTEM 
/NOSILENT/SOURCE 

SET DEFINE ADDRESS 

SET DISPLAY/DYNAMIC/POP/SIZE:64. The 
default window is either HI or H2, alternating 
between these two with each newly created 
display. The default display kind is "output". 

SET EDITOR/NOSTART-POSITION. 

The current image is the main image. 

SET KEY/STATE=DEFAULT 

The default language is the language of the module 
that contains the image transfer address (main 
program). 

SET LOG SYS$DISK:[ JDEBUG.LOG 

SET MARGINS 1:255 (left margin: 1, right margin: 
255) 

SET MAX_SOURCE_FILES 5 

SET MODE DYNAMIC, NOG-FLOAT, KEYPAD, 
LINE, NOSCREEN, SCROLL, SYMBOLIC 

SET OUTPUT NOLOG, NOSCREEN-LOG, 
TERMINAL, NOVERIFY 

SET PROMPT 'DBG> 

For BLISS and MACRO: SET RADIX 
HEXADECIMAL. For all other languages: SET 
RADIX DECIMAL 

The debugger looks up a symbol specified without 
a path-name prefix according to the scope search 
list 0,1, ... ,N (where N is the number of calls 
in the call stack). If the symbol is not found, the 
debugger searches the run-time symbol table, then 
the global symbol table if necessary. 

SET SEARCH NEXT,STRING 

The debugger looks for a source debugger's 
symbol table. 

For MACRO: SET STEP SOURCE, NOSILENT, 
OVER, INSTRUCTION. For all other languages: SET 
STEP SOURCE, NOSILENT, OVER, LINE. 

The values of /PAGE and /WIDTH default to those 
set at DCL level (see the VAX/VMS DCL Dictionary 
or type the DCL command HELP SET TERMINAL). 

SET TRACE/INTO/JSB/SHARE/SYSTEM 
/NOSILENT/SOURCE 
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Command Defaults 


Command 

Default 

SET TYPE 

The default type for typed locations is the 
compiler-generated type. The default type for 
other locations is long integer. 

STEP 

For MACRO: STEP/OVER/INSTRUCTION. For all 
other languages: STEP/OVER/LINE. 

TYPE 

If a module name is specified, source lines in that 
module are displayed, if available. If no module 
name is specified, the debugger uses the current 
scope search list (as established by a previous 

SET SCOPE command, or the default scope search 
list 0,1, ... ,N if no SET SCOPE command was 
issued) to find source lines for display. The 
debugger looks for the source lines of the module 
associated with each successive scope region in 
the search list until source lines are found. Also, 
if no line is specified after a single source line has 
been displayed with the TYPE command, the next 
line is displayed by default. 
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Predefined Key Functions 


When you invoke the debugger, certain predefined functions (commands, 
sequences of commands, and command terminators) are assigned to keys 
on the numeric keypad, to the right of the main keyboard. By using these 
keys you can issue certain commands with fewer keystrokes than if you were 
to type them out at the keyboard. For example, pressing the COMMA 
(,) keypad key is equivalent to typing out GO and then pressing the 
RETURN key. Terminals and workstations that have an LK201 keyboard 
have additional programmable keys compared to those on VT100 keyboards 
(for example, "Help" or "Remove"), and some of these keys are also assigned 
debugger functions. 

Use of the function keys requires that keypad mode be enabled (SET MODE 
KEYPAD). Keypad mode is enabled when you invoke the debugger. If 
you do not want keypad mode enabled, perhaps because the program being 
debugged uses the keypad for itself, you can disable keypad mode by entering 
the SET MODE NOKEYPAD command. 

The keypad key functions that are predefined when you invoke the debugger 
are identified in summary form in Figure B-l. Tables B-l through B-4 
identify all key definitions in detail. Most keys are used for manipulating 
screen displays in screen mode. To use screen mode commands, you must 
first enable screen mode: press keypad key PF3 (SET MODE SCREEN). 


B.1 DEFAULT, GOLD, and BLUE Functions 

A given key typically has three predefined functions: 

• One function is entered by pressing the given key by itself. This is the 
DEFAULT function. 

• A second function is entered by pressing the PF1 key and then the given 
key. This is the GOLD function, because PF1 is also called the GOLD 
key. 

• A third function is entered by pressing the PF4 key and then the given 
key. This is the BLUE function, because PF4 is also called the BLUE key. 

In Figure B-l, the DEFAULT, GOLD, and BLUE functions are listed within 
each key's outline, from top to bottom respectively. For example, pressing 
keypad key 0 enters the command STEP (DEFAULT function); pressing key 
PF1 and then key 0 enters the command STEP/INTO (GOLD function); 
pressing key PF4 and then key 0 enters the command STEP/OVER (BLUE 
function). 

All command sequences assigned to keypad keys are terminated (executed 
immediately) except for the BLUE functions of keys 2, 4, 6, and 8. These 
unterminated commands are symbolized with a trailing ellipsis ( ... ) in 
Figure B-l. To terminate the command, supply a parameter and then press 
RETURN. For example, to scroll down 12 lines, press key PF4, then press 
keypad key 2, then type :12 at the keyboard, then press RETURN. 
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Figure B—1 Keypad Key Functions Predefined by the Debugger 
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LK201 Keyboard: 

Press 
F1 7 
F18 
F19 
F20 


Keys 2,4,6,8 

SCROLL 

MOVE 

EXPAND 

CONTRACT 


VT-100 Keyboard: 

Type 

SET KEY/STATE=DEFAULT 
SET KEY/STATE=MOVE 
SET KEY/STATE=EXPAND 
SET KEY/STATE=CONTRACT 


Keys 2,4,6,8 
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B.2 Key Definitions Specific to LK201 Keyboards 

Table B-l lists keys that are specific to LK201 keyboards and do not appear 
on VT100 keyboards. For each key, the table identifies the equivalent 
command and, for some keys, an equivalent keypad key that you may 
use if you do not have an LK201 keyboard. 



B—2 






































































































Predefined Key Functions 


B.3 


Table B-1 Key Definitions Specific to LK201 Keyboards 


LK201 Key 

Command Sequence Invoked 

Equivalent 

Keypad Key 

F17 

SET KEY/STATE=DEFAULT 

None 

F18 

SET KEY/STATE=MOVE 

None 

F19 

SET KEY/STATE=EXPAND 

None 

F20 

SET KEY/STATE=CONTRACT 

None 

Help 

HELP KEYPAD SUMMARY 

None 

Next Screen 

SCROLL/DOWN 

2 

Prev Screen 

SCROLL/UP 

8 

Remove 

DISPLAY/REMOVE %CURSCROLL 

None 

Select 

SELECT/SCROLL %NEXTSCROLL 

3 


Keys that Scroll, Move, Expand, and Contract Displays 

By default, keypad keys 2, 4, 6, and 8 scroll the current scrolling display. 
Each key controls a direction (down, left, right, and up, respectively). By 
pressing keys F18, F19, or F20, you can place the keypad in the MOVE, 
EXPAND, or CONTRACT states. When the keypad is in the MOVE state, 
keys 2, 4, 6, and 8 may be used to move the current scrolling display down, 
left, and so on. Similarly, in the EXPAND and CONTRACT states, the four 
keys may be used to expand or contract the current scrolling display. (See 
Figure B-1 and Table B-2. Alternative key definitions for VT100 keyboards 
are described later in this section.) 

To scroll, move, expand, or contract a display, proceed as follows: 

1 Press key 3 repeatedly, as needed, to select the current scrolling display 
from the display list. 

2 Press key F17, F18, F19, or F20 to put the keypad in the DEFAULT 
(scroll), MOVE, EXPAND, or CONTRACT state, respectively. 

3 Press keys 2, 4, 6, and 8 to perform the desired function. Use the PF1 
(GOLD) and PF4 (BLUE) keys to control the amount of scrolling or 
movement. 

Table B—2 Keys that Change the Key State 


Key Description 

PF1 Invokes the GOLD function of the next key you press. 

PF4 Invokes the BLUE function of the next key you press. 

FI7 Puts the keypad in the DEFAULT state, enabling the scroll-display 

functions of keys 2, 4, 6, and 8. The keypad is in the DEFAULT state 
when you invoke the debugger. 

FI8 Puts the keypad in the MOVE state, enabling the move-display 

functions of keys 2, 4, 6, and 8. 
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Table B—2 (Cont.) Keys that Change the Key State 


Key Description 


FI9 Puts the keypad in the EXPAND state, enabling the expand-display 

functions of keys 2, 4, 6, and 8. 

F20 Puts the keypad in the CONTRACT state, enabling the contract-display 

functions of keys 2, 4, 6, and 8. 


If you have a VT100 keyboard, you can simulate the effect of LK201 keys 
FI7 through F20 by defining the key sequences GOLD-KP9 and BLUE-KP9 
(currently undefined) as shown below. With these definitions, pressing 
GOLD-KP9 will put the keypad in the DEFAULT (scroll) state; pressing 
BLUE-KP9 will cycle the keypad through the DEFAULT, MOVE, EXPAND, 
and CONTRACT states (like cycling through keys FI 7 through F20). You 
may want to store these key definitions in a command procedure, such as 
your debugger initialization file. 

DEFINE/KEY/IF_STATE=(GOLD,MOVE.GOLD.EXPAND.GOLD,CONTRACT.GOLD)/TERMINATE KP9 "Set Key/State=DEFAULT/Nolog" 
DEFINE/KEY/IF_STATE=(BLUE)/TERMINATE KP9 "Set Key/State=MOVE/Nolog" 

DEFINE/KEY/IF_STATE=(MOVE_BLUE)/TERMINATE KP9 "Set Key/State=EXPAND/Nolog" 

DEFINE/KEY/IF_STATE=(EXPANDJBLUE)/TERMINATE KP9 "Set Key/State=CONTRACT/Nolog" 

DEFINE/KEY/IF_STATE=(CONTRACT_BLUE)/TERMINATE KP9 "Set Key/State=DEFAULT/Nolog" 


B.4 Online Keypad Key Diagrams 

Online HELP for the keypad keys is available by pressing the Help key and 
also the PF2 key, either by itself or with other keys (see Table B-3). You can 
also use the SHOW KEY command to identify key definitions. 

Table B-3 Keys that Invoke Online Help to Display Keypad Diagrams 


Key or 

Key Sequence Command Sequence Invoked Description 


Help 

HELP KEYPAD SUMMARY 

PF2 

HELP KEYPAD DEFAULT 

PF1-PF2 

HELP KEYPAD GOLD 

PF4-PF2 

HELP KEYPAD BLUE 

F18-PF2 

HELP KEYPAD MOVE—DEFAULT 

F18-PF1-PF2 

HELP KEYPAD MOVE_GOLD 

F18-PF4-PF2 

HELP KEYPAD MOVE-BLUE 

F19-PF2 

HELP KEYPAD EXPAND-DEFAULT 


Shows a diagram of the keypad keys and 
summarizes each key's function. 

Shows a diagram of the keypad keys and their 
DEFAULT functions. 

Shows a diagram of the keypad keys and their 
GOLD functions. 

Shows a diagram of the keypad keys and their 
BLUE functions. 

Shows a diagram of the keypad keys and their 
MOVE DEFAULT functions. 

Shows a diagram of the keypad keys and their 
MOVE GOLD functions. 

Shows a diagram of the keypad keys and their 
MOVE BLUE functions. 

Shows a diagram of the keypad keys and their 
EXPAND DEFAULT functions. 
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Table B-3 (Cont.) Keys that Invoke Online Help to Display Keypad Diagrams 


Key or 

Key Sequence Command Sequence Invoked Description 


F19-PF1-PF2 
F19-PF4-PF2 
F20-PF2 
F20-PF1-PF2 
F20-PF4-PF2 


HELP KEYPAD EXPAND_GOLD 
HELP KEYPAD EXPAND_BLUE 
HELP KEYPAD CONTRACT_DEFAULT 
HELP KEYPAD CONTRACT_GOLD 
HELP KEYPAD CONTRACT_BLUE 


Shows a diagram of the keypad keys and their 
EXPAND GOLD functions. 

Shows a diagram of the keypad keys and their 
EXPAND BLUE functions. 

Shows a diagram of the keypad keys and their 
CONTRACT DEFAULT functions. 

Shows a diagram of the keypad keys and their 
CONTRACT GOLD functions. 

Shows a diagram of the keypad keys and their 
CONTRACT BLUE functions. 


B.5 Debugger Key Definitions 

Table B-4 identifies all key definitions. 

Table B-4 Debugger Key Definitions 


Key 

State 

Commands Invoked or Function 

0 

DEFAULT 

STEP 


GOLD 

STEP/INTO 


BLUE 

STEP/OVER 

1 

DEFAULT 

EXAMINE. Examines the logical successor of 
the current entity, if one is defined (the next 
location). 


GOLD 

EXAMINE \ Lets you examine the logical 
predecessor of the current entity, if one is 
defined (the previous location). 


BLUE 

Undefined 

2 

DEFAULT 

SCROLL/DOWN 


GOLD 

SCROLL/BOTTOM 


BLUE 

SCROLL/DOWN (not terminated). To terminate 
the command, supply the number of lines to be 
scrolled (:n) and/or a display name. 


MOVE 

MOVE/DOWN 


MOVE-GOLD 

MOVE/DOWN :999 


MOVE-BLUE 

MOVE/DOWN: 5 


EXPAND 

EXPAND/DOWN 


EXPAND-GOLD 

EXPAND/DOWN:999 


EXPAND-BLUE 

EXPAND/DOWN: 5 


CONTRACT 

EXPAND/DOWN:-1 


CONTRACT-GOLD 

EXPAND/DOWN :-999 
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Table B-4 (Cont.) Debugger Key Definitions 


Key State 

Commands Invoked or Function 

CONTRACT_BLUE 

EXPAND/DOWN:-5 

3 DEFAULT 

SELECT/SCROLL %NEXTSCROLL. Selects as 
the current scrolling display the next display in 
the display list after the current scrolling display. 

GOLD 

SELECT/OUTPUT %NEXTOUTPUT. Selects the 
next output display in the display list as the 
current output display. 

BLUE 

SELECT/SOURCE %NEXTSOURCE. Selects the 
next source display in the display list as the 
current source display. 

4 DEFAULT 

SCROLL/LEFT 

GOLD 

SCROLL/LEFT :255 

BLUE 

SCROLL/LEFT (not terminated). To terminate 
the command, supply the number of lines to be 
scrolled (:n) and/or a display name. 

MOVE 

MOVE/LEFT 

MOVE-GOLD 

MOVE/LEFT :999 

MOVE-BLUE 

MOVE/LEFT: 10 

EXPAND 

EXPAND/LEFT 

EXPAND-GOLD 

EXPAND/LEFT :999 

EXPAND-BLUE 

EXPAND/LEFT: 10 

CONTRACT 

EXPAND/LEFT:-1 

CONTRACT-GOLD 

EXPAND/LEFT :-999 

CONTRACT-BLUE 

EXPAND/LEFT:-10 

5 DEFAULT 

EXAM/SOURCE .%SOURCE_SCOPE\%PC; 
EXAM/INST .0\%PC. In line (noscreen) mode, 
lets you see the source line or instruction to 
be executed next. In screen mode, centers the 
current source display on the next source line to 
be executed, and the current instruction display 
on the next instruction to be executed. 

GOLD 

SHOW CALLS 

BLUE 

SHOW CALLS 3 

6 DEFAULT 

SCROLL/RIGHT 

GOLD 

SCROLL/RIGHT :255 

BLUE 

SCROLL/RIGHT (not terminated). To terminate 
the command, supply the number of lines to be 
scrolled (:n) and/or a display name. 

MOVE 

MOVE/RIGHT 

MOVE-GOLD 

MOVE/RIGHT :999 

MOVE-BLUE 

MOVE/RIGHT: 10 

EXPAND 

EXPAND/RIGHT 
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Table B-4 (Cont.) Debugger Key Definitions 


Key 

State 

Commands Invoked or Function 


EXPAND_GOLD 

EXPAND/RIGHT :999 


EXPAND_BLUE 

EXPAND/RIGHT: 10 


CONTRACT 

EXPAND/RIGHT :-1 


CONTRACT_GOLD 

EXPAND/RIGHT :-999 


CONTRACT_BLUE 

EXPAND/RIGHT10 

7 

DEFAULT 

DISPLAY SRC AT LH1, INST AT RH1, OUT 

AT S45, PROMPT AT S6; SELECT/SCROLL 
/SOURCE SRC; SELECT/INST INST; SELECT 
/OUT OUT. Displays the SRC, INST, OUT, and 
PROMPT displays with the proper attributes. 


GOLD 

DISPLAY INST AT LH1, REG AT RH1, OUT AT 
S45, PROMPT AT S6; SELECT/SCROLL/INST 
INST; SELECT/OUT OUT. Displays the INST, 
REG, OUT, and PROMPT displays with the 
proper attributes. Useful for MACRO. 


BLUE 

Undefined 

8 

DEFAULT 

SCROLL/UP 


GOLD 

SCROLL/TOP 


BLUE 

SCROLL/UP (not terminated). To terminate the 
command, supply the number of lines to be 
scrolled (:n) and/or a display name. 


MOVE 

MOVE/UP 


MOVE-GOLD 

MOVE/UP:999 


MOVE-BLUE 

MOVE/UP:5 


EXPAND 

EXPAND/UP 


EXPAND-GOLD 

EXP AND/UP: 999 


EXPAND-BLUE 

EXPAND/UP:5 


CONTRACT 

EXPAND/UP:-1 


CONTRACT-GOLD 

EXPAND/UP:-999 


CONTRACT-BLUE 

EXPAND/UP:-5 

9 

DEFAULT 

DISPLAY %NEXTDISP. Displays the next display 
in the display list through its current window 
(removed displays are not included). 


GOLD 

Undefined 


BLUE 

Undefined 

PF1 


See Table B-2. 

PF2 


See Table B-3. 

PF3 

DEFAULT 

SET MODE SCREEN; SET STEP NOSOURCE. 
Enables screen mode and suppresses the output 
of source lines that would normally appear in the 
output display (since that output is redundant 
when the source display is present). 
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Table B-4 (Cont.) Debugger Key Definitions 


Key 

State 

Commands Invoked or Function 


GOLD 

SET MODE NOSCREEN; SET STEP SOURCE. 
Disables screen mode and restores the output 
of source lines. 


BLUE 

DISPLAY/GENERATE. Regenerates the contents 
of all automatically updated displays. 

PF4 


See Table B-2. 

COMMA 

DEFAULT 

GO 


GOLD 

Undefined 


BLUE 

SELECT/INSTRUCTION %NEXTINST. Selects 
the next instruction display in the display list as 
the current instruction display. 

MINUS 

DEFAULT 

DISPLAY %NEXTDISP AT SI2345, PROMPT 

AT S6; SELECT/SCROLL %CURDISP. Displays 
the next display in the display list at essentially 
full screen (top of screen to top of PROMPT 
display). Selects that display as the current 
scrolling display. 


GOLD 

Undefined 


BLUE 

DISPLAY SRC AT HI, OUT AT S45, PROMPT 
AT S6; SELECT/SCROLL/SOURCE SRC; SELECT 
/OUT OUT. Displays the SRC, OUT, and 
PROMPT displays with the proper attributes. 

This is the default display configuration for all 
languages except MACRO. 

ENTER 


Lets you enter (terminate) a command. Same 
effect as RETURN. 

PERIOD 


Cancels the effect of pressing state keys which 
do not lock the state, such as GOLD and BLUE. 
Does not affect the operation of state keys 
which lock the state, such as MOVE, EXPAND, 
and CONTRACT. 

Next 


SCROLL/DOWN 

Screen 

Prev 


SCROLL/UP 

Screen 

Remove 


DISPLAY/REMOVE %CURSCROLL. Removes the 
current scrolling display from the display list. 

Select 


SELECT/SCROLL %NEXTSCROLL. Selects as 
the current scrolling display the next display in 
the display list after the current scrolling display. 

F17 


See Table B-2. 

F18 


See Table B-2. 

F19 


See Table B-2. 
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Table B-4 (Cont.) 

Debugger Key Definitions 

Key State 

Commands Invoked or Function 

F20 

See Table B—2. 

CTRL/W 

DISPLAY/REFRESH 
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Screen-Mode Reference Information 


This appendix contains summarized reference information related to screen 
mode. The following topics are covered: 

• Display kinds 

• Display attributes 

• Predefined displays 

• Screen-related built-in symbols 

• Screen dimensions and predefined windows 


C.1 Display Kinds 

The SET DISPLAY and DISPLAY commands accept these display-kind 
keywords and parameters: 

DO (cmd-list) Specifies an automatically updated output display. 

The commands in cmd-list are executed each 
time the debugger gains control. Their output 
forms the contents of the display. 

INSTRUCTION Specifies an instruction display. If selected as 

the current instruction display with the SELECT 
/INSTRUCTION command, it will display the 
output from subsequent EXAMINE/INSTRUCTION 
commands. 

INSTRUCTION (command) Specifies an automatically updated instruction 

display. The command specified must be 
an EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 

Specifies an output display. If selected as the 
current output display with the SELECT/OUTPUT 
command, it will display any debugger output 
that is not directed to another display. If selected 
as the current input display with the SELECT 
/INPUT command, it will echo debugger input. 

If selected as the current error display with 
the SELECT/ERROR command, it will display 
debugger diagnostic messages. 

Specifies an automatically updated register 
display. The display is updated each time the 
debugger gains control. 

Specifies a source display. If selected as 
the current source display with the SELECT 
/SOURCE command, it will display the output 
from subsequent TYPE or EXAMINE/SOURCE 
commands. 


OUTPUT 

REGISTER 

SOURCE 
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SOURCE (command) 


Specifies an automatically updated source display. 
The command specified must be a TYPE or 
EXAMINE/SOURCE command. The source 
display is updated each time the debugger gains 
control. 


C.2 Display Attributes 

The SELECT command assigns an attribute to a display according to the 
qualifier used with that command. The following list identifies each of the 
SELECT command qualifiers, its effect, and the display kinds to which you 
can assign that attribute. 


SELECT 

Qualifier Description 

/ERROR Selects the specified display as the current error display. 

Directs any subsequent debugger diagnostic message to that 
display. It must be either an output display or the PROMPT 
display. If no display is specified, selects the PROMPT 
display as the current error display. 

/INPUT Selects the specified display as the current input display. 

Echoes any subsequent debugger input in that display. 

It must be an output display. If no display is specified, 
unselects the current input display: debugger input is not 
echoed to any display. 

/INSTRUCTION Selects the specified display as the current instruction 
display. Directs the output of any subsequent EXAMINE 
/INSTRUCTION command to that display. It must be an 
instruction display. Keypad key sequence BLUE-COMMA 
selects the next instruction display in the display list as 
the current instruction display. If no display is specified, 
unselects the current instruction display: no display has the 
instruction attribute. 

/OUTPUT Selects the specified display as the current output display. 

Directs any subsequent debugger output to that display, 
except where a particular type of output is being directed 
to another display (such as diagnostic messages going to 
the current error display). The specified display must be 
either an output display or the PROMPT display. Keypad 
key sequence GOLD-3 selects the next output display in the 
display list as the current output display. If no display is 
specified, selects the PROMPT display as the current output 
display. 

/PROGRAM Selects the specified display as the current program display. 

Tries to force any subsequent program input or output to 
that display. Currently, only the PROMPT display may be 
specified. If no display is specified, unselects the current 
program display: program output is no longer forced to the 
PROMPT display. 
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SELECT 

Qualifier 

Description 

/PROMPT 

Selects the specified display as the current prompt display, 
where the debugger prompts for input. Currently, only the 
PROMPT display may be specified. You cannot unselect the 
PROMPT display. 

/SCROLL 

Selects the specified display as the current scrolling display. 
Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify 
any display (however, note that the PROMPT display cannot 
be scrolled). /SCROLL is the default if you do not specify a 
qualifier with the SELECT command. Key 3 selects as the 
current scrolling display the next display in the display list 
after the current scrolling display. If no display is specified, 
unselects the current scrolling display: no display has the 
scroll attribute. 

/SOURCE 

Selects the specified display as the current source display. 
Directs the output of any subsequent TYPE or EXAMINE 
/SOURCE command to that display. It must be a source 
display. Keypad key sequence BLUE-3 selects the next 
source display in the display list as the current source 
display. If no display is specified, unselects the current 
source display: no display has the source attribute. 

By default, when you invoke screen mode, the predefined displays are 
selected for attributes as follows: 

Attribute 

Predefined Display 

Error 

PROMPT 

Input 

no display selected 

Instruction 

INST (for MACRO only) 

Output 

OUT 

Program 

PROMPT 

Prompt 

PROMPT 

Scroll 

SRC for all languages except MACRO, INST for MACRO 

Source 

SRC for all languages except MACRO 


C.3 Predefined Displays 

Properties of the predefined displays SRC, OUT, PROMPT, INST and REG 
are summarized in this section. 
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C.3.1 


SRC (Source Display) 

Note: The debugger does not provide source line display for MACRO. If the 
language is set to MACRO, SRC is marked as removed from the display 
pasteboard. The INST display is put in its place. 

SRC is an automatically updated source display. It shows the source code of 
the module being debugged, if that source code is available. The arrow points 
to the source line corresponding to the current PC location. 

The default characteristics of the SRC display are the following: 


Display kind 
Attributes 
Position 
Size 

Dynamic 


source (examine/source .%source_scope\%pc) 
scroll, source for all languages except MACRO 
HI (removed for MACRO) 

64 lines 
Yes 


% SOURCE—SCOPE is a built-in scope that signifies scope 0 when source 
lines are available for scope 0. Otherwise, % SOURCE —SCOPE signifies 
scope N, where N is the first level down the call stack where source lines are 
available. Thus, when source lines are available for the currently executing 
module, the SRC display is centered on the PC location. If source lines are 
not available for that module, the debugger attempts to display source lines 
in the caller of that module (scope 1). If source lines are also not available 
at that level, the debugger tries scope 2, and so on. If no source lines are 
available for any scope, the debugger issues a diagnostic message. 


C.3.2 OUT (Output Display) 

OUT shows all debugger output that is not directed to another display. 
The default characteristics of the OUT display are the following: 

Display kind output 

Attribute output 

Position S45 

Size 100 lines 

Dynamic Yes 


C.3.3 PROMPT (Prompt Display) 

PROMPT is where the debugger prompts for input and, by default, forces 
program output and prints debugger diagnostic messages. 

PROMPT has different properties and restrictions than other displays. This is 
to eliminate possible confusion when manipulating that display: 

• You cannot hide, remove, permanently delete, or scroll PROMPT. 

• You can contract PROMPT down to 2 lines. You cannot contract 
PROMPT horizontally. 
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The default characteristics of the PROMPT display are the following: 


Display kind 
Attributes 

Position 

Size 

Dynamic 


program 

error, prompt, program (no other display may have the prompt 
or program attributes) 

S6 

Not applicable (PROMPT is not scrollable) 

Yes 


C.3.4 INST (Instruction Display) 

INST is an automatically updated instruction display. It shows the instruction 
stream of the routine being debugged. The instructions displayed are decoded 
from the image being debugged. The arrow points to the instruction at your 
current PC. 


The default characteristics of the INST display are the following: 


Display kind 
Attributes 
Position 
Size 

Dynamic 


instruction (examine/instruction .0\%pc) 
instruction, scroll (for MACRO only) 

HI, removed for all languages except MACRO 

64 lines 

Yes 


C.3.5 


REG (Register Display) 


REG automatically shows the current values of all VAX machine registers, 
the four condition code bits (C,V, Z, and N) of the processor status longword 
(PSL), and the top several values on the stack and on the current argument 
list. Values in this display are highlighted when they change as you execute 
the program. 

The default characteristics of the REG display are the following: 


Display kind 
Attribute 
Position 
Size 

Dynamic 


register 

none 

RH1, removed 
64 lines 
No 


C.4 Screen-Related Built-in Symbols 

The following built-in symbols are available for specifying displays and screen 
parameters in language expressions: 

• %SOURCE—SCOPE—Used to display source code. %SOURCE-SCOPE 
is described in Section 3.1. 

• %PAGE, %WIDTH—Used to specify the current screen height and width. 

• %CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, 

%NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE—Pseudo-display 
names, used to specify displays in the display list. 
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C.4.1 Terminal Height and Width 

The built-in symbols %PAGE and %WIDTH return, respectively, the current 
height and width of the terminal screen. These symbols may be used in 
various expression, such as for window specifications. For example, the 
following command defines a window named MIDDLE that occupies a region 
around the middle of the screen: 

DBG> SET WINDOW MIDDLE AT (7.PAGE/4,7.PAGE/2,7.WIDTH/4,*/.WIDTH/2) 


C.4.2 Pseudo-Display Names 

Each time you refer to a specific display with a DISPLAY or SET DISPLAY 
command, the display list is updated and reordered, if necessary. The most 
recently referenced display is put at the tail of the display list since that 
display is pasted last on the pasteboard (the display list may be identified by 
issuing a SHOW DISPLAY command). 

The debugger accepts seven pseudo-display names that refer to displays 
relative to their positions in the display list. These names, listed below, 
let you refer to displays by their relative positions in the list instead of by 
their explicit names. Pseudo-display names are used mainly in keypad or 
command definitions. 


Pseudo-display names treat the display list as a circular list. Therefore, you 
can issue any commands that use pseudo-display names to cycle through the 
display list until you reach the display you want. 


%CURDISP 

%CURSCROLL 

%NEXTDISP 

%NEXTINST 

%NEXTOUTPUT 

%NEXTSCROLL 

%NEXTSOURCE 


Refers to the current display. This is the display most recently 
referenced with a DISPLAY or SET DISPLAY command—the 
least occluded display. 

Refers to the current scrolling display. This is the default 
display for the SCROLL, MOVE, and EXPAND commands, as 
well as for the associated keypad keys (2, 4, 6, and 8). 

Refers to the next display in the list after the current display. 
The next display is the display that follows the topmost 
display. Because the display list is circular, this is the display 
at the bottom of the pasteboard—the most occluded display. 

Refers to the next instruction display in the display list after 
the current instruction display. The current instruction display 
is the display which receives the output from EXAMINE 
/INSTRUCTION commands. 

Refers to the next output display in the display list after the 
current output display. An output display receives debugger 
output that is not already directed to another display. 

Refers to the next display in the display list after the current 
scrolling display. 

Refers to the next source display in the display list after the 
current source display. The current source display is the 
display which receives the output from TYPE and EXAMINE 
/SOURCE commands. 
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C.5 


Screen Dimensions and Predefined Windows 

On a VT-series terminal, the screen consists of 24 lines by 80 or 132 columns. 
On a Micro VAX workstation, the screen is larger in both height and width. 
The debugger can accommodate screen sizes up to 100 lines by 255 columns. 

All of the debugger predefined windows are identified in this section. The 
window names apply to all screen sizes; however, the lines and columns 
specified apply only to VT-series terminals whose width is set at 80 columns. 
In windows occupying the left or right half of the screen (columns 1-40 and 
42-80, respectively), column 41 is reserved as a border. 

In addition to the full height and width of the screen, the predefined windows 
include all possible regions that result from dividing the screen vertically into 
halves, thirds, quarters, and sixths, and horizontally into left and right halves. 

The following conventions apply to the names of predefined windows: the 
prefixes L and R denote left and right windows, respectively; other letters 
denote the full screen (FS) or fractions of the screen height (H: half, T: third, 
Q: quarter, S: sixth); the trailing numbers denote specific fractions of the 
screen height, starting from the top (for example, Tl, T2, and T3 are the top, 
middle and bottom third). 


Window Start-lin,Lin-count, Window 

Name Start-col,Col-count Location 


Full screen 
Top half 
Full screen 
Bottom half 


FS 

(1,23,1,80) 

HI 

(1,11,1,80) 

H12 

(1,23,1,80) 

H2 

(13,11,1,80) 

LFS 

(1,23,1,40) 

LH1 

(1,11,1,40) 

LH12 

(1,23,1,40) 

LH2 

(13,1 1,1,40) 

LQ1 

(1,5,1,40) 

LQ12 

(1,11,1,40) 

LQ123 

(1,17,1,40) 

LQ1234 

(1,23,1,40) 

LQ2 

(7,5,1,40) 

LQ23 

(7,1 1,1,40) 

LQ234 

(7,17,1,40) 

LQ3 

(13,5,1,40) 

LQ34 

(13,11,1,40) 

LQ4 

(19,5,1,40) 

LSI 

(1,3,1,40) 

LSI 2 

(1,7,1,40) 

LSI 23 

(1,11,1,40) 

LSI234 

(1,15,1,40) 

LSI 2345 

(1,19,1,40) 


Left full screen 

Left half 

Left full screen 

Left bottom half 

Left top quarter 

Left top half 

Left top three quarters 

Left full screen 

Left second quarter 

Left middle two quarters 

Left bottom three quarters 

Left third quarter 

Left bottom half 

Left bottom quarter 

Left top sixth 

Left top third 

Left top half 

Left top two thirds 

Left top five sixths 
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Window 

Name 

Start-lin,Lin-count, 
Start-col,Col-count 

Window 

Location 

LSI 23456 

(1,23,1,40) 

Left half 

LS2 

(5,3,1,40) 

Left second sixth 

LS23 

(5,7,1,40) 

Left second and third sixths 

LS234 

(5,1 1,1,40) 

Left second, third, and fourth sixths 

LS2345 

(5,15,1,40) 

Left second, third, fourth, and fifth sixths 

LS23456 

(5,19,1,40) 

Left bottom five sixths 

LS3 

(9,3,1,40) 

Left third sixth 

LS34 

(9,7,1,40) 

Left middle third 

LS345 

(9,11,1,40) 

Left third, fourth, and fifth sixths 

LS3456 

(9,15,1,40) 

Left bottom two thirds 

LS4 

(13,3,1,40) 

Left fourth sixth 

LS45 

(13,7,1,40) 

Left fourth and fifth sixths 

LS456 

(13,11,1,40) 

Left bottom half 

LS5 

(17,3,1,40) 

Left fifth sixth 

LS56 

(17,7,1,40) 

Left bottom third 

LS6 

(21,3,1,40) 

Left bottom sixth 

LT1 

(1,7,1,40) 

Left top third 

LT12 

(1,15,1,40) 

Left top two thirds 

LT123 

(1,23,1,40) 

Left half 

LT2 

(9,7,1,40) 

Left middle third 

LT23 

(9,15,1,40) 

Left bottom two thirds 

LT3 

(17,7,1,40) 

Left bottom third 

Q1 

(1,5,1,80) 

Top quarter 

Q12 

(1,11,1,80) 

Top half 

Q123 

(1,17,1,80) 

Top three quarters 

Q1234 

(1,23,1,80) 

Full screen 

Q2 

(7,5,1,80) 

Second quarter 

Q23 

(7,11,1,80) 

Middle two quarters 

Q234 

(7,17,1,80) 

Bottom three quarters 

Q3 

(13,5,1,80) 

Third quarter 

Q34 

(13,1 1,1,80) 

Bottom half 

Q4 

(19,5,1,80) 

Bottom quarter 

RFS 

(1,23,42,39) 

Right full screen 

RH1 

(1,1 1,42,39) 

Right top half 

RH12 

(1,23,42,39) 

Right full screen 

RH2 

(13,11,42,39) 

Right bottom half 

RQ1 

(1,5,42,39) 

Right top quarter 

RQ12 

(1,11,42,39) 

Right top half 

RQ123 

(1,17,42,39) 

Right top three quarters 
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Window 

Name 

Start-lin,Lin-count, 
Start-col. Col-count 

Window 

Location 

RQ1234 

(1,23,42,39) 

Right half 

RQ2 

(7,5,42,39) 

Right second quarter 

RQ23 

(7,11,42,39) 

Right middle two quarters 

RQ234 

(7,17,42,39) 

Right bottom three quarters 

RQ3 

(13,5,42,39) 

Right third quarter 

RQ34 

(13,11,42,39) 

Right bottom half 

RQ4 

(19,5,42,39) 

Right bottom quarter 

RSI 

(1,3,42,39) 

Right top sixth 

RSI 2 

(1,7,42,39) 

Right top third 

RSI 23 

(1,11,42,39) 

Right top half 

RSI 234 

(1,15,42,39) 

Right top two thirds 

RSI 2345 

(1,19,42,39) 

Right top five sixths 

RSI 23456 

(1,23,42,39) 

Right full screen 

RS2 

(5,3,42,39) 

Right second sixth 

RS23 

(5,7,42,39) 

Right second and third sixths 

RS234 

(5,11,42,39) 

Right second, third, and fourth sixths 

RS2345 

(5,15,42,39) 

Right second, third, fourth, and fifth sixths 

RS23456 

(5,19,42,39) 

Right bottom five sixths 

RS3 

(9,3,42,39) 

Right third sixth 

RS34 

(9,7,42,39) 

Right middle third 

RS345 

(9,1 1,42,39) 

Right third, fourth, and fifth sixths 

RS3456 

(9,15,42,39) 

Right bottom two thirds 

RS4 

(13,3,42,39) 

Right fourth sixth 

RS45 

(13,7,42,39) 

Right fourth and fifth sixth 

RS456 

(13,11,42,39) 

Right bottom half 

RS5 

(17,3,42,39) 

Right fifth sixth 

RS56 

(17,7,42,39) 

Right bottom third 

RS6 

(21,3,42,39) 

Right bottom sixth 

RT1 

(1,7,42,39) 

Right top third 

RT12 

(1,15,42,39) 

Right top two thirds 

RT 123 

(1,23,42,39) 

Right full screen 

RT2 

(9,7,42,39) 

Right middle third 

RT23 

(9,15,42,39) 

Right bottom two thirds 

RT3 

(17,7,42,39) 

Right bottom third 

SI 

(1,3,1,80) 

Top sixth 

S12 

(1,7,1,80) 

Top third 

SI 23 

(1,1 1,1,80) 

Top half 

SI 234 

(1,15,1,80) 

Top four sixths 

SI 2345 

(1,19,1,80) 

Top five sixths 
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Window 

Name 

Start-lin,Lin-count, 
Start-col,Col-count 

Window 

Location 

SI23456 

(1,23,1,80) 

Full screen 

S2 

(5,3,1,80) 

Top second sixth 

S23 

(5,7,1,80) 

Second and third sixths 

S234 

(5,11,1,80) 

Second, third, and fourth sixths 

S2345 

(5,15,1,80) 

Second, third, fourth, and fifth sixths 

S23456 

(5,19,1,80) 

Bottom five sixths 

S3 

(9,3,1,80) 

Third sixth 

S34 

(9,7,1,80) 

Middle third 

S345 

(9,1 1,1,80) 

Third, fourth, and fifth sixths 

S3456 

(9,15,1,80) 

Bottom two thirds 

S4 

(13,3,1,80) 

Fourth sixth 

S45 

(13,7,1,80) 

Fourth and fifth sixths 

S456 

(13,11,1,80) 

Bottom half 

S5 

(17,3,1,80) 

Fifth sixth 

S56 

(17,7,1,80) 

Bottom third 

S6 

(21,3,1,80) 

Bottom sixth 

T1 

(1,7,1,80) 

Top third 

T12 

(1,15,1,80) 

Top two thirds 

T123 

(1,23,1,80) 

Full screen 

T2 

(9,7,1,80) 

Middle third 

T23 

(9,15,1,80) 

Bottom two thirds 

T3 

(17,7,1,80) 

Bottom third 


C-10 











Built-in Symbols and Logical Names 


This appendix identifies all of the debugger built-in symbols and logical 
names. 


D.1 




SS$_DEBUG Condition 

SS$_DEBUG (defined in SYS$LIBRARY:STARLET.OLB) is a condition you 
can signal from your program to invoke the debugger. Signalling SS$_ 
DEBUG from your program is equivalent to typing CTRL/Y followed by the 
DCL command DEBUG at that point. 

You can pass commands to the debugger at the time you signal it with 
SS$_DEBUG. The commands you wish the debugger to execute should 
be specified as you would enter them at the DBG> prompt. Multiple 
commands should be separated by semicolons. The commands should be 
passed by reference as an ASCIC string. See your language documentation 
for details on constructing an ASCIC string. 

For example, to invoke the debugger and issue a SHOW CALLS command at 
a given point in your program, you could insert the following code in your 
program (BLISS example): 

LIB$SIGNAL (SS$_DEBUG, 1, UPLIT BYTE ('/.ASCIC ’SHOW CALLS’)); 

You can obtain the definition of SS$_DEBUG at compile time from 
the appropriate STARLET or SYSDEF file for your language (for 
example STARLET.L32 for BLISS or FORSYSDEF.TLB for FORTRAN). 

You can also obtain the definition of SS$_DEBUG at link time in 
SYS$LIBRARY:STARLET.OLB (this method is less desirable). 
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Logical Names 


The following list identifies debugger-specific process logical names. 


Logical 

Name 

Description 

LIBSDEBUG 

Points to the current debugger. Default: 

SYSSSH ARE DEBUG.EXE 

DBGSHELP 

Points to the debugger online-Help library file. Default: 
SYS$HELP:DEBUGHLP.HLB. 

DBGSINIT 

Points to your debugger initialization file. Default: no debugger 
initialization file. 

DBGSINPUT 

Points to your input device. Default: SYSSlNPUT. 

DBGSOUTPUT 

Points to your output device. Default: SYSSOUTPUT. 


You can use the DCL command ASSIGN or DEFINE to assign values to these 
logical names. For example, the following command tells the debugger the 
location of your debugger initialization file: 
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$ DEFINE DBG$INIT DISK$:[JONES.COMFILES]DEBUGINIT.COM 

Note that LIB$DEBUG, DBG$HELP, and DBG$INIT accept a full or partial 
VAX/VMS file specification, as well as a search list. 


D.2.1 Using DBG$INPUT and DBG$OUTPUT 

DBG$INPUT and DBG$OUTPUT are useful when, for example, you are 
debugging a screen-oriented program. You can assign DBG$INPUT and 
DBG$OUTPUT to one terminal line (for example, TTD1:). Another terminal 
line (for example, TTD2:) can be devoted to the program's input and output. 
Then, you can 

• Enter debugger commands and observe debugger output at TTD1:. 

• Enter program input and observe program output at TTD2:. 

Note that, on a properly secured system, terminals are protected so that you 
can log in but you cannot allocate a terminal. Use the following command to 
determine the owner UIC of TTD1: 

$ SHOW DEVICE/FULL TTD1: 

Typically, you will need to ask your system manager (or a suitably privileged 
person) to provide you with read access to the terminal. For example: 

$ SET PROTECTION=WORLD:READ/DEVICE/OWNER=[SYSTEM] TTD1: 

The above technique provides world read access and, therefore, allows other 
users to also allocate and perform I/O to TTD1:. The following technique is 
preferred because it uses an access control list (ACL). Assume that your UIC 
is [DEVEL,JONES]. Then the system manager can restrict device access to you 
alone as follows: 

$ SET DEVICE/ACL*(IDENT*[DEVEL,JONES],ACCESS=READ) TTD1: 

Another method is for you to enable SYSPRIV privilege in your own process 
so that you can allocate TTD1: without allowing the world to allocate it. 
However, note that it is risky to debug an erroneous program with SYSPRIV 
enabled. 

Once you have read access to the terminal, you can allocate it so that you 
have exclusive access to it: 

$ ALLOCATE TTD1: 

Now you can assign DBG$INPUT and DBG$OUTPUT: 

$ DEFINE DBG$INPUT TTD1: 

$ DEFINE DBGIOUTPUT TTD1: 

The remaining step is to make sure that the terminal type is known to the 
system. Use the following command: 

$ SHOW DEVICE/FULL TTD1: 

If the device type is "unknown", make it known to the system as follows 
(assuming the terminal is a VT100): 

$ SET TERMINAL/PERMANENT/DEVICE=VT100 TTD1: 

Now you can run your program and observe debugger input and output at 
TTD1. When finished, deallocate TTD1: as follows: 

$ DEALLOCATE TTD1: 
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D.3 Built-in Symbols 

The debugger's built-in symbols provide options for specifying entities in 
your program and let you control the debugger's scanning of language 
expressions. Most of the debugger built-in symbols have a percent sign (%) 
prefix. Descriptions of these symbols are organized as follows in the next 
sections: 

• %R0 through %R11, %PC, %PSL, %SP, %AP, %FP—Used to specify the 
VAX registers. 

• %NAME—Used to construct identifiers. 

• %PARCNT—Used in command procedures to count parameters passed. 

• %BIN, %DEC, %HEX, %OCT—Used to control radix. 

• Period (.), RETURN key, circumflex (~), backslash (\), %CURLOC, 
%NEXTLOC, %PREVLOC, %CURVAL, % LABEL, %LINE—Used to 
specify program locations and the current value of an entity. 

• Plus sign (+), minus sign (-), multiplication sign (*), division sign (/), 
at sign ((a)), period (.), bit field operator ( <p,s,e> )—Used as operators 
in address expressions. 

• %ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME, %EXC_ 
NUMBER, %EXC_SEVERITY—Used to obtain information about 
exceptions. 

• % ACTIVE _TASK, % C ALLER _TASK, %NEXT_TASK, %TASK, 

% VISIBLE—TASK—Used to specify tasks in Ada tasking programs. 

• %CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, 
%NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE—Used in screen 
mode to specify displays in the display list (these built-in symbols are 
described in Appendix C). 

• %PAGE, % WIDTH, %SOURCE-SCOPE—Used to specify the current 
terminal-screen height and width, and to display source code in screen 
mode (these built-in symbols are described in Appendix C). 


D.3.1 Specifying the VAX Registers 

The debugger built-in symbol for a VAX register is the register name preceded 
by the percent sign (%). These symbols are identified in the following list. 


Symbol 

Description 


%R0 . . . %R 11 

General purpose registers RO . 

. . R1 1 

%PC 

Program counter 


%PSL 

Processor status longword 


%SP 

Stack pointer 


%AP 

Argument pointer 


%FP 

Frame pointer 
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For example, the following EXAMINE command obtains the contents of the 
PC (the address contained in the PC): 

DBG> EXAMINE ‘/.PC 
M0DV/.PC: 1553 


D.3.2 Constructing Identifiers 

The %NAME built-in symbol lets you construct identifiers that are not 
ordinarily legal in the current language. The syntax is as follows: 

•/.NAME ’character-string’ 

In the following example, the variable with the name '12' is examined: 

DBG> EXAMINE ‘/.NAME ’12’ 

In the following example, the compiler-generated label P.AAA is examined: 

DBG> EXAMINE ‘/.NAME ’P.AAA’ 


D.3.3 Counting Parameters Passed to Command Procedures 

The %PARCNT built-in symbol may be used within a command procedure 
that accepts a variable number of actual parameters (%PARCNT is defined 
only within a debugger command procedure). 

%PARCNT specifies the number of actual parameters passed to the current 
command procedure. In the following example, command procedure 
ABC.COM is invoked and three parameters are passed: 

DBG> ©ABC 111,222,333 

Within ABC.COM, %PARCNT now has the value 3. %PARCNT is then used 
as a loop counter to obtain the value of each parameter passed to ABC.COM: 

DBG> FOR I = 1 TO 7.PARCNT DO (DECLARE X:VALUE; EVALUATE X) 


D.3.4 Controlling Radix 


The built-in symbols %BIN, %DEC, %HEX, and %OCT are used to 
specify that a numeric literal that follows (or all numeric literals in a 
parenthesized expression that follows) should be interpreted in binary, 
decimal, hexadecimal, or octal radix, respectively. 

For example: 

DBG> EVALUATE/DEC '/.HEX 10 
16 

DBG> EVALUATE/DEC ‘/.HEX (10 + 10) 

32 

DBG> EVALUATE/DEC '/.BIN 10 
2 

DBG> EVALUATE/DEC '/.OCT (10 + 10) 

16 

DBG> EVALUATE/HEX '/.DEC 10 
OA 
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D.3.5 


Specifying Program Locations and the Current Value of an Entity 

The following built-in symbols let you specify program locations and the 
current value of an entity. 


Symbol 

Description 

%CURLOC 
. (period) 

Current logical entity—the program location last referenced by 
an EXAMINE or DEPOSIT command. 

%NEXTLOC 
RETURN key 

Logical successor of the current entity—the program location 
that logically follows the location last referenced by an 
EXAMINE or DEPOSIT command. Because the RETURN key is 
a command terminator, it can be used only where a command 
terminator is appropriate (for example, immediately after 
EXAMINE, but not immediately after DEPOSIT). 

%PREVLOC 
* (circumflex) 

Logical predecessor of current entity—the program location 
that logically precedes the location last referenced by an 
EXAMINE or DEPOSIT command. 

%CURVAL 
\ (backslash) 

Value last displayed by an EVALUATE or EXAMINE command, 
or deposited by a DEPOSIT command. 

%LABEL 

Specifies that the numeric literal that follows is a program 
label (for languages like FORTRAN that have numeric program 
labels). You can qualify the label with a path-name prefix that 
specifies the containing module. 

%LINE 

Specifies that the numeric literal that follows is a line number 
in your program. You can qualify the line number with a 
path-name prefix that specifies the containing module. 


In the following example, the variable WIDTH is examined; the value 12 
is then deposited into the current location (WIDTH); this is verified by 
examining the current location: 

DBG> EXAMINE WIDTH 
MOD\WIDTH: 7 
DBG> DEPOSIT . = 12 
DBG> EXAMINE . 

M0D\WIDTH: 12 
DBG> EXAMINE ‘/.CURLOC 
MODNWIDTH: 12 

In the next example, the next and previous locations in an array are examined: 

DBG> EXAMINE PRIMES(4) 

MOD\PRIMES(4): 7 
DBG> EXAMINE ‘/.NEXTLOC 
M0D\PRIMES(5) : 11 

DBG> EXAMINE IRET1 ! Examine next location 

M0D\PRIMES(6): 13 

DBG> EXAMINE ‘/.PREVLOC 

M0D\PRIMES(5): 11 

DBG> EXAMINE * 

MOD\PRIMES(4): 7 

Note that using the RETURN key to signify the logical successor does not 
apply to all contexts. For example, you cannot press the RETURN key after 
typing the command DEPOSIT to indicate the next location, whereas you can 
always use the symbol %NEXTLOC for that purpose. 

In the next example, a breakpoint is set at label 10 of module MOD4: 

DBG> SET BREAK M0D4V/.LABEL 10 
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D.3.6 


Using Operators in Address Expressions 

The operators that may be used in address expressions are listed below. A 
unary operator has one operand. A binary operator has two operands. 


Symbol 

Description 

Plus sign ( + ) 

Unary or binary operator. As a unary operator, 
indicates the unchanged value of its operand. As 
a binary operator, adds the preceding operand and 
succeeding operand together. 

Minus sign (-) 

Unary or binary operator. As a unary operator, 
indicates the negation of the value of its operand. As 
a binary operator, subtracts the succeeding operand 
from the preceding operand. 

Multiplication sign (*) 

Binary operator. Multiplies the preceding operand by 
the succeeding operand. 

Division sign (/) 

Binary operator. Divides the preceding operand by 
the succeeding operand. 

At sign (@) 

Period (.) 

Unary operators. In an address expression, the at 
sign (@) and period (.) each function as a "contents- 
of" operator. The "contents-of" operator causes its 
operand to be interpreted as a virtual address and 
thus requests the contents of (or value residing at) 
that address. 

Bit field <p,s,e> 

Unary operator. You can apply bit field selection 
to an address-expression. To select a bit field, you 
supply a bit offset (p), a bit length (s), and a sign 
extension bit (e), which is optional. 


In the following example, the value contained in the virtual memory location 
X + 4 bytes is obtained: 

EXAMINE X + 4 

The remaining examples illustrate use of the "contents-of" operator. In the 
next example, the instruction at the current PC is obtained (the instruction 
whose address is contained in the PC and which is about to execute): 

DBG> EXAMINE .‘/.PC 
MODV/.LINE 5: PUSHL S~#8 

In the next example, the source line at the PC location one level down the 
call stack is obtained (at the call to routine SWAP): 

DBG> EXAMINE/SOURCE .1\%PC 
MAIN\SWAP\7.LINE 28: SWAP (X. Y) ; 

For the next example, assume that the value of pointer variable PTR is 
7FF00000 hexadecimal, the virtual address of an entity that you want 
to examine. Assume further that the value of this entity is 3FF00000 
hexadecimal. The following command shows how to examine entity: 

DBG> EXAMINE/LONG .PTR 
7FF00000: 3FF00000 
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In the next example, the contents-of operator (at sign or period) is used 
with the current location operator (period) to examine a linked list of three 
quadword-integer pointer variables (identified as LI, L2, and L3 in the 
illustration that follows). P is a pointer to the start of the list. The low 
longword of each pointer variable contains the address of the next variable; 
the high longword of each variable contains its integer value (8, 6, and 12 
respectively). 


P: 


I 9B40 


I--+ LI L2 L2 

+ | +-+ +-+ +-+ 

+-->| 9BDA I--->| 9BF4 |--->| 0000 I 

| - , | - | | . | 

I8| I6| I 12 I 


DBG> SET TYPE QUADWORD; SET 
DBG> EXAMINE .P 

00009BC2: 00000008 00009BDA 

DBG> EXAMINE ®. 

00009BDA: 00000006 00009BF4 

DBG> EXAMINE .. 

00009BF4: 0000000C 00000000 


RADIX HEX 

! Examine the entity whose address 
! is contained in P 
! High word has value 8, low word 
! has address of next entity (9BDA) 

! Examine the entity whose address 
! is contained in the current entity 
! High word has value 6, low word 
! has address of next entity (9BF4) 

! Examine the entity whose address 
! is contained in the current entity 
! High word has value 12 (dec.), low word 
! has address 0 (end of list) 


The next example shows how to use the bit-field operator. To examine the 
address expression X_NAME starting at bit 3 with a length of 4 bits and no 
sign extension, you would issue the following command: 


DBG> EXAMINE X.NAME <3,4 t 0> 


D.3.7 Obtaining Information About Exceptions 

The following built-in symbols let you obtain information about the current 
exception and use that information to qualify breakpoints. 


Symbol 

Description 

%ADAEXC_ 

NAME 

Ada exception name of current exception (for Ada programs 
only) 

%EXC_FACILITY 

Name of facility of current exception 

%EXC_NAME 

Name of current exception 

%EXC_NUMBER 

Number of current exception 

%EXC_SE VERITY 

Severity code of current exception 


For example: 

DBG> EVALUATE 7,EXC_NAME 
"FLTDIV.F" 

DBG> SET BREAK/EXCEPTION WHEN (7.EXC.NAME = M FLTDIV_F") 


DBG> EVALUATE 7.EXC.NUMBER 
12 

DBG> EVALUATE/C0NDITI0N.VALUE */.EXC_NUMBER 

V.SYSTEM-F-ACCVIO, access violation at PC !XL, virtual address !XL 
DBG> SET BREAK/EXCEPTION WHEN (*/,EXC_NUMBER = 12) 
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D.3.8 Specifying Ada Tasks 

The following built-in symbols may be used to specify the tasks of an Ada 
tasking program in debugger commands (these built-in symbols apply only to 
Ada tasking programs). 


Symbol 

Description 

% ACTIVE-TASK 

Currently active task—the task that will execute when a GO 
or STEP command is issued. 

%CALLER_T ASK 

Task that is the entry caller of the active task during a task 
rendezvous. 

%NEXT_TASK 

Next task on debugger's task list after the task that is 
currently visible. 

%TASKn 

Specifies a task by means of its task ID (n is a decimal 
integer assigned by the VAX Ada run-time library to each 
task as it is created). 

% VISIBLE-TASK 

Currently visible task—the task that is the context for an 
EXAMINE command, for example. 


Two examples follow. See the VAX Ada documentation for additional details. 

DBG> EXAMINE MONITOR.TASK 

M0D\M0NIT0R_TASK: '/.TASK 2 


DBG> WHILE '/.NEXT NEQ '/.ACTIVE DO (SET TASK '/.NEXT; SHOW CALLS) 
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E Summary of Debugger Support for 
Languages 


The debugger supports most of the VAX/VMS-supported languages. 
Debugger support is summarized in this chapter for the following language 
keywords (used with the SET LANGUAGE command): ADA, BASIC, BLISS, 
C, COBOL, DIBOL, FORTRAN, MACRO, PASCAL, PLI, RPG, SCAN, and 
UNKNOWN. For each language, the following information is provided: 

• Supported operators in language expressions 

• Supported constructs in language expressions 

• Supported data types 

• Any other language-specific features (for example, event keywords in the 
case of ADA and SCAN). 

For further information, refer to the documentation furnished with a particular 
language. 


E. 1 Debugger Support for Language ADA 

This section includes information about debugger support for ADA. 


E. 1.1 Supported ADA Operators in Language Expressions 

Supported ADA operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus (identity) 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

« 

Multiplication 

Infix 

/ 

Division 

Infix 

MOD 

Modulus 

Infix 

REM 

Remainder 

Infix 

«* 

Exponentiation 

Prefix 

ABS 

Absolute value 

Infix 

& 

Concatenation (only string types) 

Infix 

= 

Equality (only scalar and string types) 

Infix 

/= 

Inequality (only scalar and string types) 

Infix 

> 

Greater than (only scalar and string types) 

Infix 

> = 

Greater than or equal (only scalar and string types) 
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Kind 

Symbol 

Function 

Infix 

< 

Less than (only scalar and string types) 

Infix 

<= 

Less than or equal (only scalar and string types) 

Prefix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND (not for bit arrays) 

Infix 

OR 

Logical OR (not for bit arrays) 

Infix 

XOR 

Logical exclusive OR (not for bit arrays) 


Notes 

1 The debugger does not support: 

• Operations on entire arrays or records. 

• The short-circuit control forms: and then, or else. 

• The membership tests: in, not in. 

2 The debugger does not support user-defined operators. 


E.1.2 


Supported Constructs in Language and Address Expressions for 
ADA 


Supported constructs in language and address expressions for ADA follow. 


Symbol 

Construct 

< > 

Subscripting 


Record component selection 

.ALL 

Pointer dereferencing 


E. 1.3 Supported ADA Data Types 

Supported ADA data types follow. 


ADA Type 

INTEGER 
SHORT_INTEGER 
SHORT_SHORT_INTEGER 
SYSTEM. UNSIGNED_QUADWORD 
SYSTEM. UNSIGNED_LONGWORD 
SYSTEM. UNSIGNED_WORD 
SYSTEM.UNSIGNED_BYTE 
FLOAT 

SYSTEM.F_FLOAT 
SYSTEM. D_FLOAT 


VAX Type Name 

Longword Integer (L) 
Word Integer (W) 

Byte Integer (B) 
Quadword Unsigned (QU) 
Longword Unsigned (LU) 
Word Unsigned (WU) 
Byte Unsigned (BU) 
F_Floating (F) 

F_Floating (F) 

D_Floating (D) 
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ADA Type 

VAX Type Name 

LONG_FLOAT 

D_Floating (D), if pragma LONG_FLOAT(D_ 
FLOAT) is in effect. G_Floating (G), if 
pragma LONG_FLOAT(G_FLOAT) is in 
effect. 

SYSTEM. G_FLOAT 

G_Floating (G) 

SYSTEM.H_FLOAT 

H—Floating (H) 

LONG_LONG_FLOAT 

H_Floating (H) 

Fixed 

(None) 

STRING 

ASCII Text (T) 

BOOLEAN 

Aligned Bit String (V) 

BOOLEAN 

Unaligned Bit String (VU) 

Enumeration 

For any enumeration type whose value 
fits into an unsigned byte or word: Byte 
Unsigned (BU) or Word Unsigned (WU), 
respectively. Otherwise: No corresponding 
VAX data type. 

Arrays 

(None) 

Records 

(None) 

Access (pointers) 

(None) 

Tasks 

(None) 


E. 1.4 Supported ADA Predefined Attributes 

Supported ADA predefined attributes follow. 


Attribute 


Debugger Support 


P'CONSTRAINED 

For a prefix P that denotes a record object with 
discriminants. The value of P'CONSTRAINED reflects the 
current state of P (constrained or unconstrained). 

P'FIRST 

For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the lower bound of P. 

P'FIRST 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the lower bound 
of the first index range. 

P'FIRST(N) 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the lower bound 
of the N-th index range. 

P'LAST 

For a prefix P that denotes an enumeration type, or a 
subtype of an enumeration type. Yields the upper bound of 
P. 

P'LAST 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the upper 
bound of the first index range. 
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Attribute 

Debugger Support 

P'LAST(N) 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the upper 
bound of the N-th index range. 

P'LENGTH 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the number of 
values of the first index range (zero for a null range). 

P'LENGTH(N) 

For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the number of 
values of the N-th index range (zero for a null range). 

P'POS(X) 

For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the position number of the 
value X. The first position is 0. 

P'PRED(X) 

For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P which 
has a position number one less than that of X. 

P'SIZE 

For a prefix P that denotes an object. Yields the number of 
bits allocated to hold the object. 

P'SUCC(X) 

For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P which 
has a position number one more than that of X. 

P'VAL(N) 

For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P which 
has the position number N. The first position is 0. 


E.1.5 Support for ADA Tasking Programs and Events 


E. 1.5.1 Task States 

The following task-state keywords may be used with the SHOW TASK 
/STATE command: 


Task State 

Description 

RUNNING 

Currently running on the processor. This is the active task. 

READY 

Eligible to execute and waiting for the processor to be made 
available. 

SUSPENDED 

Suspended—that is, waiting for an event rather than for the 
availability of the processor. For example, when a task is 
created, it remains in the suspended state until it is activated. 

TERMINATED 

Terminated. 
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E.1.5.2 Task Substates 

The following task-substate keywords may appear in a SHOW TASK display: 


Task Substate 

Description 

Abnormal 

Task has been aborted. 

Accept 

Task is waiting at an accept statement that is not inside 
a select statement. 

Activating 

Task is elaborating its declarative part. 

Activating tasks 

Task is waiting for tasks it has created to finish 
activating. 

Completed [abn] 

Task is completed due to an abort statement, but is not 
yet terminated. In Ada, a task awaiting dependent tasks 
at its "end" is called "completed". After the dependent 
tasks are terminated, the state changes to terminated. 

Completed [exc] 

Task is completed due to an unhandled exception, but is 
not yet terminated. In Ada, a task awaiting dependent 
tasks at its "end" is called "completed". After the 
dependent tasks are terminated, the state changes to 
terminated. 

Completed 

Task is completed. No abort statement was issued, and 
no unhandled exception occurred. 

Delay 

Task is waiting at a delay statement. 

Dependents 

Task is waiting for dependent tasks to terminate. 

Dependents [exc] 

Task is waiting for dependent tasks to allow an 
unhandled exception to propagate. 

Entry call 

Task is waiting for its entry call to be accepted. 

Invalid state 

There is a bug in the VAX Ada run-time library. 

I/O or AST 

Task is waiting for I/O completion or some AST. 

Not yet activated 

Task is waiting to be activated by the task that created 
it. 

Select or delay 

Task is waiting at a select statement with a delay 
alternative. 

Select or term. 

Task is waiting at a select statement with a terminate 
alternative. 

Select 

Task is waiting at a select statement with neither an 
else, delay, or terminate alternative. 

Shared resource 

Task is waiting for an internal shared resource. 

Terminated [abn] 

Task was terminated by an abort. 

Terminated [exc] 

Task was terminated because of an unhandled 
exception. 

Terminated 

Task terminated normally. 

Timed entry call 

Task is waiting in a timed entry call. 


E.1.5.3 Supported ADA Events 

The following ADA event keywords may be used with the /EVENT qualifier 
of the SET BREAK, SET TRACE, CANCEL BREAK, and CANCEL TRACE 
commands. You can also display these event keywords with the SHOW 
EVENT-FACILITY command. 
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Exception-Related Events 


Event Name 

Description 

HANDLED 

Triggers when an exception is about to be handled 
in some Ada exception handler, including an others 
handler (see Chapter 7). 

HANDLED_OTHERS 

Triggers only when an exception is about to be 
handled in an others Ada exception handler (see 
Chapter 7). 

Task Exception-Related Events 

Event Name 

Description 

RENDEZVOUS-EXCEPTION 

Triggers when an exception begins to propagate 
out of a rendezvous. 

DEPENDENTS—EXCEPTION 

Triggers when an exception causes a task to 
wait for dependent tasks in some scope. Often 
immediately precedes a deadlock. 

Task Termination Events 

Event Name 

Description 

TERMINATED 

Triggers when a task is terminating, whether 
normally, by abort, or by exception. 

EXCEPTION-TERMINATED 

Triggers when a task is terminating due to an 
exception. 

ABORT-TERMINATED 

Triggers when a task is terminating due to an 
abort. 

Low-Level Task Scheduling Events 

Event Name 

Description 

RUN 

Triggers when a task is about to run. 

PREEMPTED 

Triggers when a task is being preempted from the 
RUN state. 

ACTIVATING 

Triggers when a task is about to begin its 
activation (that is, at the beginning of the 
elaboration of the declarative part of its task 
body). 

SUSPENDED 

Triggers when a task is about to be suspended. 


E.2 Debugger Support for BASIC 

This section includes information about debugger support for BASIC. 
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E.2.1 Supported BASIC Operators in Language Expressions 

Supported BASIC operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition, String concatenation 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

* 

Exponentiation 

Infix 

= 

Equal to 

Infix 

<> 

Not equal to 

Infix 

> < 

Not equal to 

Infix 

> 

Greater than 

Infix 

> = 

Greater than or equal to 

Infix 

=> 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

O 

Less than or equal to 

Infix 

= < 

Less than or equal to 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

IMP 

Bit-wise implication 

Infix 

EQV 

Bit-wise equivalence 


E.2.2 


Supported Constructs in Language and Address Expressions for 
BASIC 

Supported constructs in language and address expressions for BASIC follow. 


Symbol 

Construct 

< > 

Subscripting 

Record component selection 


E.2.3 Supported BASIC Data Types 

Supported BASIC data types follow. 
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BASIC Type 

VAX Type Name 

BYTE 

Byte Integer (B) 

WORD 

Word Integer (W) 

LONG 

Longword Integer (L) 

SINGLE 

F_Floating (F) 

DOUBLE 

D_Floating (D) 

GFLOAT 

G_Floating (G) 

HFLOAT 

H—Floating (H) 

DECIMAL 

Packed Decimal (P) 

STRING 

ASCII Text (T) 

RFA 

(None) 

Arrays 

(None) 

Records 

(None) 


Notes 

1 Expressions that overflow in the BASIC language will not necessarily 
overflow when evaluated by the debugger. The debugger will try to 
compute a numerically correct result, even when the BASIC rules call 
for overflows. This difference is particularly likely to affect DECIMAL 
computations. 

2 BASIC constants of the forms [radix]"numeric-string"[type] (such as 
"12.34"GFLOAT) or n% (such as 25% for integer 25) are not supported in 
debugger expressions. 


E.3 Debugger Support for BLISS 

This section includes information about debugger support for BLISS. 


E.3.1 Supported BLISS Operators in Language Expressions 

Supported BLISS operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 


Indirection 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

MOD 

Remainder 

Infix 


Left shift 

Infix 

EQL 

Equal to 
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Kind 

Symbol 

Function 

Infix 

EQLU 

Equal to 

Infix 

EQLA 

Equal to 

Infix 

NEQ 

Not equal to 

Infix 

NEQU 

Not equal to 

Infix 

NEQA 

Not equal to 

Infix 

GTR 

Greater than 

Infix 

GTRU 

Greater than unsigned 

Infix 

GTRA 

Greater than unsigned 

Infix 

GEQ 

Greater than or equal to 

Infix 

GEQU 

Greater than or equal to unsigned 

Infix 

GEQA 

Greater than or equal to unsigned 

Infix 

LSS 

Less than 

Infix 

LSSU 

Less than unsigned 

Infix 

LSSA 

Less than unsigned 

Infix 

LEQ 

Less than or equal to 

Infix 

LEQU 

Less than or equal to unsigned 

Infix 

LEQA 

Less than or equal to unsigned 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

EQV 

Bit-wise equivalence 


E.3.2 


Supported Constructs in Language and Address Expressions for 
BLISS 

Supported constructs in language and address expressions for BLISS follow. 


Symbol 

Construct 

M 

Subscripting 

[fldname] 

Field selection 

<p,s,e> 

Bit field selection 


E.3.3 Supported BLISS Data Types 

Supported BLISS data types follow. 
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BLISS Type 

VAX Type Name 

BYTE 

Byte Integer (B) 

WORD 

Word Integer (W) 

LONG 

Longword Integer (L) 

BYTE UNSIGNED 

Byte Unsigned (BU) 

WORD UNSIGNED 

Word Unsigned (WU) 

LONG UNSIGNED 

Longword Unsigned (LU) 

VECTOR 

(None) 

BITVECTOR 

(None) 

BLOCK 

(None) 

BLOCKVECTOR 

(None) 

REF VECTOR 

(None) 

REF BITVECTOR 

(None) 

REF BLOCK 

(None) 

REF BLOCKVECTOR 

(None) 


E.4 Debugger Support for Language C 

This section includes information about debugger support for C. 


E.4.1 Supported C Operators in Language Expressions 

Supported C operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

* 

Indirection 

Prefix 

& 

Address of 

Prefix 

SIZEOF 

Size of 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

% 

Remainder 

Infix 

< < 

Left shift 

Infix 

> > 

Right shift 

Infix 

== 

Equal to 

Infix 

!= 

Not equal to 

Infix 

> 

Greater than 

Infix 

> = 

Greater than or equal to 

Infix 

< 

Less than 
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Kind 

Symbol 

Function 

Infix 

<= 

Less than or equal to 

Prefix 

(tilde) 

Bit-wise NOT 

Infix 

& 

Bit-wise AND 

Infix 

1 

Bit-wise OR 

Infix 

- 

Bit-wise exclusive OR 

Prefix 

! 

Logical NOT 

Infix 

&& 

Logical AND 

Infix 

II 

Logical OR 


Supported Constructs in Language and Address Expressions for C 

Supported constructs in 

language and address expressions for C follow. 

Symbol Construct 

[ ] Subscripting 


Structure component selection 

-> Pointer dereferencing 

Supported C Data Types 


Supported C data types follow. 

C Type 

VAX Type Name 

INT 

Longword Integer (L) 

UNSIGNED INT 

Longword Unsigned (LU) 

SHORT INT 

Word Integer (W) 

UNSIGNED SHORT INT 

Word Unsigned (WU) 

CHAR 

Byte Integer (B) 

UNSIGNED CHAR 

Byte Unsigned (BU) 

FLOAT 

F_Floating (F) 

DOUBLE 

D_Floating (D) 

ENUM 

(None) 

STRUCT 

(None) 

UNION 

(None) 

Pointers 

(None) 

Arrays 

(None) 


Notes 

1 Symbol names are case-sensitive for language C, meaning that uppercase 
and lowercase letters are treated as different characters. 
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2 Since the exclamation point (!) is an operator in C, it cannot be used 
as the comment delimiter. When the language is set to C, the debugger 
instead accepts /* as the comment delimiter. The comment continues 
to the end of the current line. (A matching */ is neither needed nor 
recognized.) To permit debugger log files to be used as debugger input, 
the debugger still recognizes ! as a comment delimiter if it is the first 
non-blank character on a line. 

3 The debugger accepts the prefix asterisk (*) as an indirection operator 
in both C language expressions and debugger address expressions. In 
address expressions, prefix is synonymous to prefix or "(a)" when 
the language is set to C. 

4 The debugger does not support any of the assignment operators in C (or 
any other language) in order to prevent unintended modifications to the 
program being debugged. Hence such operators as =, +=, -=, ++, and—are 
not recognized. If you wish to alter the contents of a memory location, 
you must do so with an explicit DEPOSIT command. 


E.5 Debugger Support for Language COBOL 

This section includes information about debugger support for COBOL. 


E.5.1 Supported COBOL Operators in Language Expressions 

Supported COBOL operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

= 

Equal to 

Infix 

NOT = 

Not equal to 

Infix 

> 

Greater than 

Infix 

NOT < 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

NOT > 

Less than or equal to 

Infix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND 

Infix 

OR 

Logical OR 
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E.5.2 


Supported Constructs in Language and Address Expressions for 
COBOL 

Supported constructs in language and address expressions for COBOL follow. 


Symbol Construct 

( ) Subscripting 

OF Record component selection 

IN Record component selection 


E.5.3 Supported COBOL Data Types 

Supported COBOL data types follow. 


COBOL Type 

VAX Type Name 

COMP 

Longword Integer (L,LU) 

COMP 

Word Integer (W,WU) 

COMP 

Byte Integer (B,BU) 

COMP 

Quadword Integer (Q,QU) 

COMP-1 

F_Floating (F) 

COMP-2 

D_Floating (D) 

COMP-3 

Packed Decimal (P) 

INDEX 

Longword Integer (L) 

Alphanumeric 

ASCII Text (T) 

Records 

(None) 

Numeric Unsigned (NU) 

(None) 

Leading Separate Sign (NL) 

(None) 

Leading Overpunched Sign (NLO) 

(None) 

Trailing Separate Sign (NR) 

(None) 

Trailing Overpunched Sign (NRO) 

(None) 


Notes 

1 The debugger can show source text included in a program with the COPY 
or COPY REPLACING verb. However, when COPY REPLACING is 
used, the debugger always shows the original source text as it appeared 
before text replacement. In other words, the original source file is shown 
instead of the modified source text generated by the COPY REPLACING 
verb. 

2 The debugger cannot show the original source lines associated with the 
code for a REPORT section. You can see the DATA SECTION source 
lines associated with a REPORT, but no source lines are associated with 
the compiled code that generates the report. 
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E.6 Debugger Support for Language DIBOL 

This section includes information about debugger support for DIBOL. 


E.6.1 Supported DIBOL Operators in Language Expressions 

Supported DIBOL operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

# 

Round 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

// 

Division with fractional result 

Infix 

.EQ. 

Equal to 

Infix 

.NE. 

Not equal to 

Infix 

.GT. 

Greater than 

Infix 

.GE. 

Greater than or equal to 

Infix 

.LT. 

Less than 

Infix 

.LE. 

Less than or equal to 

Infix 

.NOT. 

Logical NOT 

Infix 

.AND. 

Logical AND 

Infix 

.OR. 

Logical OR 

Infix 

.XOR. 

Exclusive OR 


E.6.2 


Supported Constructs in Language and Address Expressions for 
DIBOL 

Supported constructs in language and address expressions for DIBOL follow. 


Symbol 

Construct 

< > 

Substring 

N 

Subscripting 


Record component selection 


E.6.3 Supported DIBOL Data Types 

Supported DIBOL data types follow. 
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DIBOL Type 

VAX Type Name 

11 

Byte Integer (B) 

12 

Word Integer (W) 

14 

Longword Integer (L) 

Pn 

Packed Decimal String (P) 

Pn.m 

Packed Decimal String (P) 

Dn 

Numeric String, Zoned Sign (NZ) 

Dn.m 

Numeric String, Zoned Sign (NZ) 

An 

ASCII Text (T) 

Arrays 

(None) 

Records 

(None) 


E.7 Debugger Support for Language FORTRAN 

This section includes information about debugger support for FORTRAN. 


E.7.1 Supported FORTRAN Operators in Language Expressions 

Supported FORTRAN operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

// 

Concatenation 

Infix 

.EQ. 

Equal to 

Infix 

.NE. 

Not equal to 

Infix 

.GT. 

Greater than 

Infix 

GE. 

Greater than or equal to 

Infix 

.LT. 

Less than 

Infix 

.LE. 

Less than or equal to 

Prefix 

.NOT. 

Logical NOT 

Infix 

.AND. 

Logical AND 

Infix 

.OR. 

Logical OR 

Infix 

XOR. 

Exclusive OR 

Infix 

.EQV. 

Equivalence 

Infix 

.NEQV. 

Exclusive OR 
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E.7.2 Supported Constructs in Language and Address Expressions for 
FORTRAN 

Supported constructs in language and address expressions for FORTRAN 
follow. 


Symbol Construct 

( ) Subscripting 

Record component selection 


E.7.3 Supported FORTRAN Predefined Symbols 

Supported FORTRAN predefined symbols follow. 


Symbol 

Description 

.TRUE. 

Logical True 

.FALSE. 

Logical False 


E.7.4 Supported FORTRAN Data Types 

Supported FORTRAN data types follow. 


FORTRAN Type 

VAX Type Name 

LOGICAL* 1 

Byte Unsigned (BU) 

LOGICAL*2 

Word Unsigned (WU) 

LOGICAL*4 

Longword Unsigned (LU) 

INTEGER*2 

Word Integer (W) 

INTEGER*4 

Longword Integer (L) 

REAL*4 

F_Floating (F) 

REAL*8 

D_Floating (D) 

REAL*8 

G_Floating (G) 

REAL* 16 

H_Floating (H) 

COMPLEX*8 

F_Complex (FC) 

COMPLEX* 16 

D_Complex (DC) 

COMPLEX* 16 

G_Complex (GC) 

CHARACTER 

ASCII Text (T) 

Arrays 

(None) 

Records 

(None) 


Notes 

1 Even though the VAX type codes for unsigned integers (BU, WU, LU) are 
used internally to describe the LOGICAL data types, the debugger (like 
the compiler) treats LOGICAL variables and values as being signed when 
used in language expressions. 
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2 The debugger prints the numeric values of LOGICAL variables or 
expressions instead of TRUE or FALSE. Normally, only the low-order 
bit of a LOGICAL variable or value is significant (0 is FALSE and 1 is 
TRUE). However, VAX FORTRAN does allow all bits in a LOGICAL 
value to be manipulated and LOGICAL values can be used in integer 
expressions. For this reason, it is at times necessary to see the entire 
integer value of a LOGICAL variable or expression, and that is what the 
debugger shows. 

3 COMPLEX constants such as (1.0,2.0) are not supported in debugger 
expressions. 


E.8 Debugger Support for Language MACRO 

This section includes information about debugger support for MACRO. 


E.8.1 Supported Operators in Language Expressions 

Language MACRO does not have expressions in the same sense as high- 
level languages. Only assembly-time expressions and only a limited set 
of operators are accepted. To permit the MACRO programmer to use 
expressions at debug-time as freely as in other languages, the debugger 
accepts a number of operators in MACRO language expressions that are not 
found in MACRO itself. In particular, the debugger accepts a complete set of 
comparison and boolean operators modeled after BLISS. It also accepts the 
indirection operator and the normal arithmetic operators. 


Kind Symbol Function 


Prefix 

@ 

Indirection 

Prefix 


Indirection 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

MOD 

Remainder 

Infix 

@ 

Left shift 

Infix 

EQL 

Equal to 

Infix 

EQLU 

Equal to 

Infix 

NEQ 

Not equal to 

Infix 

NEQU 

Not equal to 

Infix 

GTR 

Greater than 

Infix 

GTRU 

Greater than unsigned 

Infix 

GEQ 

Greater than or equal to 

Infix 

GEQU 

Greater than or equal to unsigned 

Infix 

LSS 

Less than 
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Kind 

Symbol 

Function 

Infix 

LSSU 

Less than unsigned 

Infix 

LEQ 

Less than or equal to 

Infix 

LEQU 

Less than or equal to unsigned 

Prefix 

NOT 

Bit-wise NOT 

Infix 

AND 

Bit-wise AND 

Infix 

OR 

Bit-wise OR 

Infix 

XOR 

Bit-wise exclusive OR 

Infix 

EQV 

Bit-wise equivalence 


E.8.2 


Supported Constructs in Language and Address Expressions for 
MACRO 

Supported constructs in language and address expressions for MACRO follow. 


Symbol 

Construct 

<p / s / e> 

Bitfield selection as in BLISS 


E.8.3 Supported MACRO Data Types 

Supported MACRO data types follow. 


MACRO Type 

VAX Type Name 

(Not applicable) 

Byte Unsigned (BU) 

(Not applicable) 

Word Unsigned (WU) 

(Not applicable) 

Longword Unsigned (LU) 

(Not applicable) 

Byte Integer (B) 

(Not applicable) 

Word Integer (W) 

(Not applicable) 

Longword Integer (L) 


E.9 Debugger Support for Language PASCAL 

This section includes information about debugger support for PASCAL. 
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E.9.1 Supported PASCAL Operators in Language Expressions 

Supported PASCAL operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition, concatenation 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Real division 

Infix 

DIV 

Integer division 

Infix 

MOD 

Modulus 

Infix 

REM 

Remainder 

Infix 

** 

Exponentiation 

Infix 

IN 

Set membership 

Infix 

= 

Equal to 

Infix 

<> 

Not equal to 

Infix 

> 

Greater than 

Infix 

> = 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Prefix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND 

Infix 

OR 

Logical OR 


E.9.2 Supported Constructs in Language and Address Expressions for 
PASCAL 

Supported constructs in language and address expressions for PASCAL 
follow. 


Symbol Construct 

[ ] Subscripting 

Record component selection 
Pointer dereferencing 


E.9.3 Supported PASCAL Predefined Symbols 

Supported PASCAL predefined symbols follow. 
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Symbol 

Meaning 

TRUE 

Boolean True 

FALSE 

Boolean False 

NIL 

Nil pointer 


E.9.4 Supported PASCAL Built-In Functions 

Supported PASCAL built-in functions follow. 


Symbol Meaning 

SUCC Logical successor 

PRED Logical predecessor 


E.9.5 Supported PASCAL Data Types 

Supported PASCAL data types follow. 


PASCAL Type VAX Type Name 


INTEGER 

INTEGER 

INTEGER 

UNSIGNED 

UNSIGNED 

UNSIGNED 

SINGLE 

DOUBLE 

DOUBLE 

QUADRUPLE 

BOOLEAN 

CHAR 

VARYING OF CHAR 

SET 

FILE 

Enumerations 
Subranges 
Typed Pointers 
Arrays 
Records 
Variant records 


Longword Integer (L) 
Word Integer (W,WU) 
Byte Integer (B,BU) 
Longword Unsigned (LU) 
Word Unsigned (WU) 
Byte Unsigned (BU) 
F_Floating (F) 

D_Floating (D) 
G_Floating (G) 

H—Floating (H) 

(None) 

ASCII Text (T) 

Varying Text (VT) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 

(None) 
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E. 10 Debugger Support for Language PL/1 

This section includes information about debugger support for PL/I. 


E.10.1 Supported PL/I Operators in Language Expressions 

Supported PL/I operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

II 

Concatenation 

Infix 

= 

Equal to 

Infix 


Not equal to 

Infix 

> 

Greater than 

Infix 

> = 

Greater than or equal to 

Infix 

" < 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Infix 


Less than or equal to 

Prefix 

- 

Bit-wise NOT 

Infix 

& 

Bit-wise AND 

Infix 

1 

Bit-wise OR 


E.10.2 Supported Constructs in Language and Address Expressions for 
PL/I 

Supported constructs in language and address expressions for PL/I follow. 


Symbol 

Construct 

0 

Subscripting 


Structure component selection 

-> 

Pointer dereferencing 


E.10.3 Supported PL/I Data Types 

Supported PL/I data types follow. 
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PL/I Type 


VAX Type Name 


FIXED BINARY 
FIXED DECIMAL 
FLOAT BINARY 
FLOAT DECIMAL 
FLOAT BIN/DEC 
FLOAT BIN/DEC 
FLOAT BIN/DEC 
BIT 
BIT 

CHARACTER 

CHARACTER VARYING 

FILE 

Labels 

Pointers 

Arrays 

Structures 


Longword Integer (L) 
Packed Decimal (P) 
F_Floating (F) 
F_Floating (F) 
D_Floating (D) 
G_Floating (G) 
H_Floating (H) 

Bit (V) 

Bit Unaligned (VU) 
ASCII Text (T) 
Varying Text (VT) 
(None) 

(None) 

(None) 

(None) 

(None) 


Note 

The debugger treats all numeric constants of the form n or n.n in PL/I 
language expressions as packed decimal constants, not integer or floating¬ 
point constants, in order to conform to PL/I language rules. The internal 
representation of 10 is therefore 0C01 hexadecimal, not 0A hexadecimal. You 
can enter floating-point constants using the syntax nEn or n.nEn. There is no 
PL/I syntax for entering constants whose internal representation is Longword 
Integer. This limitation is not normally significant when debugging since the 
debugger supports the PL/I type conversion rules. However, it is possible to 
enter integer constants by using the debugger's %HEX, %OCT, and %BIN 
operators. 


E. 11 Debugger Support for Language RPG 

This section includes information about debugger support for RPG. 


E. 11.1 Supported RPG Operators in Language Expressions 

Supported RPG operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

• 

Multiplication 
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Kind Symbol Function 


Infix / 

Infix 


Infix 

NOT = 

Infix 

> 

Infix 

NOT < 

Infix 

< 

Infix 

NOT > 

Prefix 

NOT 

Infix 

AND 

Infix 

OR 


Division 

Equal to 

Not equal to 

Greater than 

Greater than or equal to 

Less than 

Less than or equal to 
Logical NOT 
Logical AND 
Logical OR 


E.11.2 Supported Constructs in Language and Address Expressions for 
RPG 


Supported constructs in language and address expressions for RPG follow. 


Symbol 

Construct 

(i 

Subscripting 


E.11.3 Supported RPG Data Types 

Supported RPG data types follow. 


RPG Type 

VAX Type Name 

Longword 

Longword Integer (L) 

Word 

Word Integer (W) 

Packed Decimal 

Packed Decimal (P) 

Character 

ASCII Text (T) 

Overpunched Decimal 

Right Overpunched Sign (NRO) 

Arrays 

(None) 

Tables 

(None) 


Note 

The debugger supports access to all RPG indicators and labels used in the 
current program. You can thus examine labels such as *DETL and indicators 
such as *INLR and *IN01 through *IN99. 


E.12 Debugger Support for SCAN 

This section includes information about debugger support for SCAN. 
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E.12.1 Supported SCAN Operators in Language Expressions 

Supported SCAN operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

& 

Concatenation 

Infix 

= 

Equal to 

Infix 

<> 

Not equal to 

Infix 

> 

Greater than 

Infix 

> = 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Prefix 

NOT 

Complement 

Infix 

AND 

Intersection 

Infix 

OR 

Union 

Infix 

XOR 

Exclusive OR 


E.12.2 Supported Constructs in Language and Address Expressions for 
SCAN 


Supported constructs in language and address expressions for SCAN follow. 


Symbol 

Construct 

o 

Subscripting 


Record component selection 

> 

Pointer dereferencing 


E.12.3 Supported SCAN Data Types 

Supported SCAN data types follow. 


SCAN Type 
BOOLEAN 
INTEGER 
POINTER 

FIXED STRING (n) 


VAX Type Name 

(None) 

Longword Integer (L) 
(None) 

TEXT with CLASS=S 
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SCAN Type 

VAX Type Name 

VARYING STRING (n) 

TEXT with CLASSA/S 

DYNAMIC STRING 

TEXT with CLASS=D 

TREE 

(None) 

TREEPTR 

(None) 

RECORD 

(None) 

OVERLAY 

(None) 


Notes 

1 There is no specific support for the following datatypes: FILE, TOKEN, 
GROUP, SET. Examining a FILL variable will display the contents of 
the specified variable as a string by default, and so may have little 
meaning. If the characteristics of the fill are known, then the appropriate 
qualifier (/HEX, and so on) applied to the command will produce a more 
meaningful display. 

2 The following examples show how to examine SCAN TREE and 
TREEPTR variables. To dump an entire SCAN tree or subtree: 

DBG> EXAMINE tree_variable([subscript], ... ) 

To dump the contents of a SCAN subtree: 

DBG> EXAMINE treeptr_variable 

To dump an entire SCAN subtree: 

DBG> EXAMINE treeptr_variable-> 

3 DEPOSIT is not supported for SCAN TREE variables. You may set 
breakpoints on any SCAN label, line number, MACRO, or PROCEDURE. 


E.12.4 Supported SCAN Events 

The following SCAN event keywords may be used with the /EVENT qualifier 
of the SET BREAK, SET TRACE, CANCEL BREAK, and CANCEL TRACE 
commands. You can also display these event keywords with the SHOW 
EVENT-FACILITY command. 


Event 

Keyword 

TOKEN 

PICTURE 

INPUT 

OUTPUT 

TRIGGER 

SYNTAX 

ERROR 


Description 

A token is built. 

An operand in a picture is being matched. 

A new line of the input stream is read. 

A new line of the output stream is written. 

A trigger macro is starting or terminating. 

A syntax macro is starting or terminating. 

Picture matching error recovery is starting or terminating. 
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E. 13 Debugger Support for Language UNKNOWN 

This section includes information about debugger support for UNKNOWN. 


E. 13.1 Supported Operators in Language Expressions 

Supported operators in language expressions follow. 


Kind 

Symbol 

Function 

Prefix 

+ 

Unary plus 

Prefix 

- 

Unary minus (negation) 

Infix 

+ 

Addition 

Infix 

- 

Subtraction 

Infix 

* 

Multiplication 

Infix 

/ 

Division 

Infix 

** 

Exponentiation 

Infix 

& 

Concatenation 

Infix 

// 

Concatenation 

Infix 

= 

Equal to 

Infix 

<> 

Not equal to 

Infix 

/= 

Not equal to 

Infix 

> 

Greater than 

Infix 

> = 

Greater than or equal to 

Infix 

< 

Less than 

Infix 

<= 

Less than or equal to 

Infix 

EQL 

Equal to 

Infix 

NEQ 

Not equal to 

Infix 

GTR 

Greater than 

Infix 

GEQ 

Greater than or equal to 

Infix 

LSS 

Less than 

Infix 

LEQ 

Less than or equal to 

Prefix 

NOT 

Logical NOT 

Infix 

AND 

Logical AND 

Infix 

OR 

Logical OR 

Infix 

XOR 

Exclusive OR 

Infix 

EQV 

Equivalence 


E.13.2 Supported Constructs in Language and Address Expressions for 
UNKNOWN 

Supported constructs in language and address expressions for UNKNOWN 
follow. 
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Symbol Construct 


() 


Subscripting 

Subscripting 

Record component selection 
Pointer dereferencing 


E.13.3 Supported UNKNOWN Data Types 


When the language is set to UNKNOWN, the debugger understands all data 
types accepted by other languages except a few very language-specific types, 
such a picture types and file types. In UNKNOWN language expressions, the 
debugger accepts most scalar VAX Standard data types. 



Notes 


1 For language UNKNOWN, the debugger accepts the dot-notation for 
record component selection. If C is a component of a record B which 
in turn is a component of a record A, C can be referenced as "A.B.C". 
Subscripts can be attached to any array components; if B is an array, for 
instance, C may be referenced as "A.B[2,3].C". 

2 For language UNKNOWN, the debugger accepts both round and square 
subscript parentheses. Hence A[2,3] and A(2,3) are equivalent. 
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A 


/ABORT qualifier*CD-129 
/AC 

See /ASCIC 
% ACTI VE_T ASK • D-8 
/ACTIVE qualifier*CD-129 
/AD 

See /ASCID 

% ADAEXC_NAME • D-7 
Address 

simple* 5-3 
Address expression 

DEPOSIT command* 1-16, 6-11, CD-40 
EVALUATE/ADDRESS command • 5-11, CD-55 
evaluating* 5-9 

EXAMINE command* 1-15, 6-5, CD-57 
GO command *3-5 
numeric literal in *5-6 
operand in • 5-9 
radix mode in *6-3 
SET BREAK command • 1-12, 3-6 
SET TRACE command* 1-13, 3-15 
SET WATCH command* 1-14, 3-12 
source display by *7-5 
type associated with *5-3 
/ADDRESS qualifier*CD-32, CD-55, CD-176 
Address space 
process* 2-5 

/AFTER qualifier*CD-88, CD-134, CD-142 
Aggregate 
data *4-8 

examining*CD-57, CD-60 
setting watchpoint on *3-13 
ALLOCATE command *9-2, CD-3 
/ALLOCATE qualifier*CD-11 1 
/ALL qualifier* 7-11 

CANCEL BREAK command*CD-11 
CANCEL DISPLAY command• CD-I3 
CANCEL IMAGE command• CD-I5 
CANCEL MODULE command• CD-I7 
CANCEL TRACE command • CD-23 
CANCEL WATCH command • CD-26 
CANCEL WINDOW command • CD-27 
DELETE/KEY command • CD-38 
DELETE command*CD-37 


/ALL qualifier (cont'd.) 

EXTRACT command*CD-66 
SEARCH command*CD-82 
SET IMAGE command*CD-102 
SET MODULE command*CD-111 
SET TASK command*CD-129 
SHOW DISPLAY command*CD-152 
SHOW KEY command*CD-157 
SHOW TASK command*CD-178 
SHOW WINDOW command*CD-185 
%AP* D-3 
Apostrophe (') 

ASCII string delimiter *6-12 
instruction delimiter*6-13 
search-string delimiter*7-10 
/APPEND qualifier*CD-66 
Argument 

specifying • 3-5 
Array *4-7, 5-8 

examining*CD-57, CD-60 
Array slice *4-8 
ASCIC data type *5-1 
/ASCIC qualifier*CD-40, CD-57 
ASCID data type *5-1 
/ASCID qualifier*CD-40, CD-57 
ASCII data 

depositing *6-12 
length of *6-12 
truncating *6-12 
ASCII data type *5-1 
/ASCII qualifier*CD-40, CD-57 
ASCIW data type *5-1 
/ASCIW qualifier*CD-40, CD-57 
ASCIZ data type *5-1 
/ASCIZ qualifier*CD-41, CD-57 
AST (asynchronous system trap) 
disabling* CD-45 

displaying AST handling conditions*CD-147 
enabling* CD-52 
Asterisk (*) 

HELP command • CD-71 
multiplication operator*5-10, D-6 
wildcard character*7-2 
/AST qualifier*CD-8 
Asynchronous system trap 
See AST 
At sign (@) 

contents-of operator • 5-10, D-6 
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At sign (@) (cont'd.) 

execute-procedure command • 2-10, CD-4 
SET ATSIGN command • CD-87 
SHOW ATSIGN command • CD-148 
ATTACH command*CD-6 
Attribute 

display *8-2, 8-16, CD-84, CD-170 
global *4-10 
symbol declaration • 4-6 
/AW 

See /ASCIW 
/AZ 

See /ASCIZ 


B 


Backslash (\)*D-5 

global-symbol specifier*4-16, 4-22, CD-119 
last-value symbol *4-5 
path-name delimiter*4-5, 4-12, 7-5 
%BIN • D-4 

/BINARY qualifier*CD-53, CD-55, CD-57 
Bit field operator ( <p,s,e> ) • 5-11, D-6 
Block *4-13 

/BOTTOM qualifier*CD-79 
/BRANCH qualifier*CD-11, CD-23, CD-88, CD- 
134, CD-188 
Breakpoint 

See also Exception breakpoint 
canceling*3-8, CD-11 
defined* 1-12, 3-6 
delayed activation of*CD-88 
displaying *3-7, CD-149 
exit handler *3-23 
setting* 1-12, 3-6, CD-88 
source display at *7-7 
/BRIEF qualifier*CD-157 
Built-in symbol *5-7, C-5, D-3 
BYTE data type *5-1 
/BYTE qualifier*CD-41, CD-58 


c 


/CALLABLE_EDT qualifier• CD-98 
/CALLABLE_LSEDIT qualifier • CD-98 
/CALLABLE—TPU qualifier • CD-98 
CALL command *3-5, CD-7 
%CALLER_T ASK • D-8 


/CALL qualifier*CD-11, CD-23, CD-89, CD-135, 
CD-188 

/CALLS qualifier*CD-178 
Call stack* 1-11 
building *3-19 

displaying *3-19, 4-1, CD-150 
CANCEL ALL command • CD-10 
CANCEL BREAK/EXCEPTION command *3-11 
CANCEL BREAK command*3-8, CD-11 
CANCEL DISPLAY command• CD-I3 
CANCEL EXCEPTION BREAK command • 3-11, 
CD-14 

CANCEL IMAGE command• CD-I5 
CANCEL MODE command *6-3, CD-16 
CANCEL MODULE command* 1-17, 4-4, 4-20, 
CD-17 

CANCEL RADIX command*CD-19 
CANCEL SCOPE command • 1-18, 4-22, CD-20 
CANCEL SOURCE command *7-3, CD-21 
CANCEL TRACE command • 3-15, CD-23 
CANCEL TYPE/OVERRIDE command • CD-25 
CANCEL WATCH command *3-13, CD-26 
CANCEL WINDOW command • 8-11, CD-27 
Circumflex 0*5-7, D-5 
/CLEAR qualifier*CD-47 
Colon (:) 

range delimiter*6-6 
Comma (,) • 6-6 
Command 

See Debugger command 
Command procedure 
debugger *2-10 
declaring parameters to *9-7 
default directory • CD-87, CD-148 
displaying commands in*2-11, CD-114 
DO clause *2-10 
exiting*CD-4, CD-62, CD-76 
invoking *2-10, CD-4 
log file as *2-12 

recreating displays*8-18, CD-66 
/COMMAND qualifier*CD-32 
Command syntax 
debugger* CD-I 
Comment 

format • CD-2 
Compiler 

/DEBUG qualifier* 1-5 
/OPTIMIZE qualifier* 1-5, 7-17 
/CONDITION—VALUE qualifier• CD-53, CD-58 
Condition handler 
executing *3-11 

Contents-of operator* 5-10, D-6 
CONTINUE command *2-13 
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CTRL/C *2-13, CD-28 

CTRL/W • CD-28 

CTRL/Y • 1-6, 2-12, CD-28 

CTRL/Z* 1-5, CD-28 

%CURDISP»C-5, C-6 

%CURLOC* 5-7, D-5 

Current entity* 5-3, 5-7, 6-6, 6-13, D-5 

%CURSCROLL • C-5, C-6 

%CURVAL* D-5 


D 


D_FLOAT data type *5-1 
/D_FLOAT qualifier*CD-41, CD-58 
Data 

aggregate *4-8 
depositing *6-11 
examining* 6-6 
name *4-6 
Data type *5-1 

displaying* CD-183 
DATE_TIME data type *5-1 
/DATE-TIME qualifier*CD-58 
DBG$HELP* D-1 
DBG$INIT • D-1 
DBGSINPUT • D-1 
DBG$OUTPUT•D-1 
DEBUG command* 1-6, 2-3, 2-13 
Debugger command 
dictionary • CD-I 

repeating• CD-68, CD-77, CD-197 
summary* 1-21 
syntax* CD-I 

/DEBUG qualifier* 1-5, 2-1, 4-2, 7-1 
Debug symbol table (DST) 

See DST 
%DEC* D-4 

/DECIMAL qualifier*CD-53, CD-55, CD-58 
DECLARE command *9-7, CD-30 
/DEFAULT qualifier*CD-58 
DEFINE/KEY command *9-9, CD-34 
DEFINE command *4-6, CD-32 

displaying default qualifiers for*CD-I51 
setting default qualifiers for*CD-93 
/DEFINED qualifier*CD-176 
DELETE/KEY command • 9-12, CD-38 
DELETE command*CD-37 
Delimiter 

depositing ASCII data *6-12 
depositing instruction • 6-13 


Delimiter (cont'd.) 

specifying precedence*5-11 
symbol • 4-8 

DEPOSIT command *1-16,6-11, CD-40 
/DIRECTORY qualifier*CD-I58 
/DIRECT qualifier*CD-176 
DISABLE AST command • CD-45 
Display 

See also Source display 
attribute*8-2, 8-16, CD-84, CD-170 
canceling • 8-8, CD-13 
contracting • 8-9, CD-64 
creating *8-10, CD-94 
defined • 8-2 
expanding *8-9, CD-64 
extracting *8-18, CD-66 
hiding *8-8, CD-48, CD-95 
identifying *8-8, CD-152 
kind *8-2, 8-11, C-1 
list *8-2, CD-152, C-6 
moving *8-9, CD-74 
pasteboard • 8-2, CD-49, CD-96 
predefined *8-3, C-3 
removing • 8-8, CD-49, CD-96 
saving *8-18, CD-78 
scrolling*8-8, CD-79 
selecting *8-16, CD-84 
showing *8-8, CD-46 
window *8-2, 8-10, C-7 
DISPLAY command *8-8, CD-46 
DO clause 

example* 1-13, 2-11 
executing *3-9 
exiting*CD-62, CD-76 
format* CD-I 

invoking command procedure • 2-10 
DO display • 8-13, C-1 
/DOWN qualifier*CD-64, CD-74, CD-79 
DST (debug symbol table) 
content of *2-1, 4-2 
creating • 4-2 
inhibiting • 2-4 
source records in *7-2 
Dynamic module setting* 1-17, 4-3, CD-109 
/DYNAMIC qualifier*CD-47, CD-95 


E 


/ECHO qualifier*CD-34 
EDIT command*CD-50 
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/EDIT qualifier*CD-21, CD-I24, CD-172 
ENABLE AST command • CD-52 
Entry mask*3-7 
/ERROR qualifier *8-16, CD-84 
EVALUATE/ADDRESS command • 5-11, CD-55 
EVALUATE command* 1-16, 6-18, CD-53 
Event facility, setting • CD-100 
/EVENT qualifier*CD-11, CD-23, CD-89, CD-135 
EXAMINE/INSTRUCTION command *8-6, C-5 
EXAMINE/SOURCE command *8-4, C-4 
EXAMINE command* 1-15, 6-5, 7-5, CD-57 
%EXC_FACILITY • 3-11, D-7 
%EXC_NAME *3-11, D-7 
%EXC_NUMBER*3-11, D-7 
%EXC_SEVERITY *3-11, D-7 
Exception breakpoint 
canceling *3-11, CD-14 
qualifying *3-1 1, D-7 
setting *3-10, CD-101 
Exception condition • 3-10 
/EXCEPTION qualifier*CD-11, CD-23, CD-89, 

CD-135, CD-188 
Exclamation point (!) • 2-12, CD-2 
log file*2-7 
Execution 

continuing after exception break *3-11 
monitoring with SHOW CALLS command* 

1-11, 3-19, CD-150 

monitoring with tracepoint* 1-13, 3-15, CD-134 
starting or continuing with CALL command* 
3-5, CD-7 

starting or continuing with GO command* 1-9, 
3-5, CD-70 

starting or continuing with STEP command* 
1-10, 3-1, CD-188 

suspending with breakpoint* 1-12, 3-6, CD-88 
suspending with exception breakpoint • 3-10, 
CD-89, CD-101 

suspending with watchpoint* 1-14, 3-12, 

CD-142 
$EXIT • 3-22 

EXIT command* 1-5, 2-13, CD-62 
Exit handler 

debugging • 3-23, CD-62 
defined *3-22 

execution sequence of *3-22 
identifying *3-23, CD-155 
EXITLOOP command*CD-63 
/EXIT qualifier*CD-50 
EXPAND command *8-9, CD-64 
Expression 

See also Address expression 
See also Language expression 


EXTRACT command • 8-18, CD-66 


F 


F_FLOAT data type • 5-1 
FLOAT data type *5-1 
/FLOAT qualifier*CD-41, CD-58 
FOR command *9-5, CD-68 
%FP* D-3 

/FULL qualifier*CD-178 


G 


G_FLOAT data type *5-1 
/G_FLOAT qualifier*CD-41, CD-58 
/GENERATE qualifier*CD-48 
Global symbol 

declaration *4-10 
scope of *4-10 
Global symbol table (GST) 

See GST 

GO command* 1-9, 3-5, CD-70 
GST (global symbol table) 
content of *2-1 
creating • 4-3 
debugger's use of *4-3 
initializing *2-5 
symbol records in *4-3 


H 


H—FLOAT data type *5-2 
/H-FLOAT qualifier*CD-41, CD-58 
Help 

online* 1-6, CD-71 
HELP command* 1-6, CD-71 
%HEX • D-4 

/HEXADECIMAL qualifier • CD-53, CD-55, CD-58 
/HIDE qualifier*CD-48, CD-95 
/HOLD qualifier*CD-129, CD-178 
Hyphen (-)*6-8 

line-continuation character • 3-9, CD-2 
subtraction operator • 5-10, D-6 
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I 



Identifier 

See also Symbol 
search string *7-11 
/IDENTIFIER qualifier • 7-11, CD-82 
/IF—STATE qualifier*CD-35 
IF command *9-6, CD-73 
Indirection operator 

See contents-of operator 
Initialization 

debugger* 1-5, 2-5 
Initialization file 
debugger *2-5 

/INPUT qualifier*8-16, CD-84, CD-117 
Instruction 

depositing *6-13 
display (INST) *8-6, C-5 
display kind *8-13, C-1 
examining *6-7 
replacing *6-14 
INSTRUCTION data type *5-2 
/INSTRUCTION qualifier• 8-6, CD-11, CD-23, CD- 
41, CD-58, CD-84, CD-89, CD-135, CD-188, 
C-5 
Interrupt 

debugging session* 1-6, 2-12, 2-13, CD-28 
program *2-3, CD-28 
/INTO qualifier*CD-89, CD-135, CD-189 
Invocation number *4-16 
path name *4-13 
syntax of • 4-19 
Invoking 

debugger*1-5 


j 


/JSB qualifier*CD-89, CD-135, CD-189 


K 


Key definition 
create* CD-34 
debugger predefined • B-1 
delete*CD-38, CD-196 
display • CD-157 
Keypad mode*CD-109, B-1 


%LABEL* D-5 

simple address *5-5 
Label 

path-name element *4-11 
program symbol *4-6 
Language 
current • 2-6 
identifying • CD-159 
setting *2-6, CD-104 
support by debugger *E-1 
Language expression 

DEPOSIT command* 1-16, 6-11, CD-40 
EVALUATE command* 1-16, 6-18, CD-53 
radix mode in *6-3 
Language-Sensitive Editor*CD-50 
/LEFT qualifier*CD-64, CD-74, CD-79 
Lexical function • C-5, D-3 
LIBSDEBUG • D-1 
%LINE • D-5 

path name *4-13 
simple address *5-4 
unnamed block *5-4 
Line mode*CD-109 
Line number 

anonymous block *4-15 
path name *4-13, 5-4 
SET BREAK command* 1-12 
SET TRACE command* 1-14 
simple address *5-4 
source display* 1-8 
source display by *7-5 
traceback information • 2-2 
/LINE qualifier* 1-13, CD-12, CD-24, CD-58, 
CD-89, CD-135, CD-189 
LINK command* 1-5, 2-1 
/LIST qualifier*7-1 

/LOCAL qualifier*CD-32, CD-37, CD-176 
Local symbol • 2-2 
/LOCK_STATE qualifier• CD-35 
Log file 

command procedure *2-12 
creating• 2-8, CD-114 
debugger* 2-7 
executing *2-12 
name *2-9, CD-105, CD-160 
Logical name 
debugger* D-1 

Logical predecessor* 5-3, 5-7, 6-8, D-5 
Logical successor• 5-3, 5-8, 6-9, 6-13, D-5 
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/LOG qualifier*CD-35, CD-38 
LONG WORD data type *5-2 
/LONGWORD qualifier*CD-41, CD-59 


M 


Margin 

setting* CD-106 

source display • 7-13, CD-106, CD-161 
/MARK_CHANGE qualifier• CD-48, CD-95 
MicroVAX 

screen size*8-19 
Mode 

CANCEL MODE *6-3, CD-16 
SET MODE [NO]DYNAMIC • CD-109 
SET MODE [NO]G_FLOAT • 6-1, CD-109 
SET MODE [NO]KEYPAD • CD-109 
SET MODE [NO]LINE • CD-109 
SET MODE [NOjSCREEN • CD-109 
SET MODE [NO]SCROLL • CD-109 
SET MODE [NOJSYMBOLIC • 6-1, CD-109 
SHOW MODE *6-1, CD-163 
/MODIFY qualifier*CD-90, CD-136 
Module 

information about *4-19, CD-164 
setting *1-17, 4-3 
/MODULE qualifier*CD-21, CD-124 
MOVE command *8-9, CD-74 


N 


%NAME • D-4 
Nested program unit *4-9 
%NEXT_TASK* D-8 
%NEXTDISP • C-5, C-6 
%NEXTINST *C-5, C-6 
%NEXTLOC • 5-8, D-5 
Next location 

See Logical successor 
%NEXTOUTPUT *C-5, C-6 
/NEXT qualifier* 7-11, CD-82 
%NEXTSCROLL• C-5, C-6 
%NEXTSOURCE • C-5, C-6 
NOP (No Operation) instruction • 6-15 
Numeric label 

path-name prefix *5-5 
simple address *5-5 
Numeric literal *5-6, 6-2 


o 


Object code *7-17 
%OCT • D-4 

/OCTAL qualifier*CD-53, CD-55, CD-59 
OCTAWORD data type *5-2 
/OCT A WORD qualifier* CD-41, CD-59 
Opcode tracing *3-17 
See also Tracepoint 
Operator 

address expression*5-10, D-6 
language expression • E-1 
radix* 6-3 

/OPTIMIZE qualifier* 1-5, 7-17 
Output 

display (OUT) *8-5, C-4 
display kind *8-14, C-1 
Output configuration 

displaying *2-8, CD-166 
setting*2-8, CD-114 
/OUTPUT qualifier*8-16, CD-85, CD-117 
/OVER qualifier*CD-90, CD-136, CD-189 
/OVERRIDE qualifier*5-2, CD-19, CD-25, CD-117, 
CD-140, CD-167, CD-183 


p 


PACKED data type *5-2 
/PACKED qualifier*CD-42, CD-59 
%PAGE*C-5 

/PAGE qualifier*8-19, CD-132 
Parameter 

language-dependent • 2-6 
language-independent • 2-7 
%PARCNT • D-4 
Parentheses (()) 

DO clause *3-9 
to delimit arguments*3-6 
Pasteboard • 8-2 
Path name 

abbreviation *4-15 
default *4-12 

distinguishing symbols *4-1 1 
numeric *4-20 

parameter in SET SCOPE *4-12 
relation to symbol* 1-10 
syntax *4-13 
%PC* D-3 
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PC 

breakpoint* 1-12 
SHOW CALLS display* 1-11 
source display* 1-8 
STEP command* 1-10 
Percent sign (%) 
symbol prefix *4-5 
Period (.) 

contents-of operator*5-10, D-6 
current entity *5-7, D-5 
symbol delimiter*4-8 
/POP qualifier*CD-48, CD-96 
Previous location 

See Logical predecessor 
%PREVLOC • 5-7, D-5 
/PRIORITY qualifier*CD-130, CD-179 
Procedure 

See also Routine 
Process address space *2-5 
Program 

display kind *8-15, C-1 
/PROGRAM qualifier*8-16, CD-85 
Program unit 

declaring symbol in *4-9 
label *4-6 

multiple invocations of *4-14 
nested *4-9 
Prompt 

debugger (DBG> )• 1-5, 2-3, CD-116 
display (PROMPT) • 8-5, C-4 
/PROMPT qualifier*8-16, CD-85 
Pseudo-display name*C-6 
%PSL* D-3 

PSL (processor status longword) 
examining *6-11 
information in *6-11, 6-16 
/PSL qualifier*CD-59 
/PSW qualifier*CD-59 
/PUSH qualifier*CD-48, CD-96 


Q 


QUADWORD data type *5-2 
/QUADWORD qualifier*CD-42, CD-59 
QUIT command*CD-76 
Quotation mark (") 

ASCII string delimiter • 6-12 
instruction delimiter*6-13 


R 


Radix 

assembly-level debugging • 6-3 
canceling* CD-19 
conversion • 6-3, D-4 
displaying* CD-167 
setting • CD-117 
Radix operator *6-3 
Record 
field *4-8 

source line correlation • 7-1 
/REFRESH qualifier*CD-48 
Register 

depositing into *6-15 
display (REG) *8-7, C-5 
display kind *8-14, C-1 
examining *6-10 
name of *4-5 
saving *3-5 
symbol* D-3 

/RELATED qualifier*CD-I7, CD-I 11, CD-164 
/REMOVE qualifier*CD-49, CD-96 
REPEAT command*CD-77 
/RESTORE qualifier*CD-130 
RETURN key 

logical successor• 5-8, 6-9, D-5 
TYPE command *7-5, CD-193 
/RETURN qualifier*CD-90, CD-136, CD-189 
/RIGHT qualifier*CD-64, CD-74, CD-79 
Routine *4-13 
calling • 3-5 
currently active *4-20 
displaying calls to *3-19 
entry mask *3-7 
innermost *4-17 
multiple invocations of *4-17 
Routine name *2-2 
path name *4-13 
SET BREAK command *3-7 
RST (run-time symbol table)* 1-17, 4-3, 9-1 
at startup*2-7 

debugger symbols in*CD-176 
deleting symbol records in *4-20, CD-17 
initializing • 2-5 

inserting symbol records in*4-20, CD-11 1 
searching *4-12 
symbol records in *4-2 
RUN command* 1-5, 2-1 
Run-time symbol table (RST) 

See RST 
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SAVE command • 8-18, CD-78 
Scope 

canceling • CD-20 
displaying* CD-168 
global symbol *4-10 
module-level • 4-22 
nonglobal symbol *4-10 
routine-level • 4-22 
search list*4-21, CD-119, CD-168 
setting* 1-18, CD-119 
symbol declaration • 4-9 
TYPE command *7-5 
/SCREEN—LAYOUT qualifier*CD-66 
Screen mode* 1-7, 8-1, CD-109 

summary reference information • C-1 
Screen size 

displaying* CD-I 81 
setting • CD-I 32 
SCROLL command *8-8, CD-79 
Scroll mode*CD-109 
/SCROLL qualifier*8-16, CD-85 
SEARCH command • 7-10, CD-81 

displaying default qualifiers for*7-12, CD-169 
setting default qualifiers for *7-1 1, CD-122 
Search list 

scope*CD-119, CD-168 
source file • 7-2, CD-21, CD-124, CD-172 
SELECT command *8-16, CD-84 
Semicolon (;) 

command separator • CD-2 
DO clause*3-9 
/SET_STATE qualifier• CD-35 
SET ATSIGN command • CD-87 
SET BREAK command • 1-12, 3-6, CD-88 
SET DEFINE command • CD-93 
SET DISPLAY command • 8-10, CD-94 
SET EDITOR command • CD-98 
SET EVENT_FACILITY command • CD-100 
SET EXCEPTION BREAK command • 3-10, CD-101 
SET IMAGE command*CD-102 

effect on symbol definitions*CD-33 
SET KEY command*CD-103 
SET LANGUAGE command *2-6, CD-104 
SET LOG command *2-9, CD-105 
SET MARGINS command • 7-14, CD-106 
SET MAX—SOURCE_FILES command • 7-16, 

CD-108 

SET MODE [NO]DYNAMIC command* 1-17, 4-4, 
CD-109 


SET MODE [NO]G_FLOAT command *6-1, CD- 
109 

SET MODE [NO]KEYPAD command • CD-109, B-1 
SET MODE [NO]LINE command • CD-109 
SET MODE [NO]SCREEN command *8-1, CD-109 
SET MODE [NO]SCROLL command*CD-109 
SET MODE [NO]SYMBOLIC command *6-1, CD- 
109 

SET MODE command • CD-109 
SET MODE SCREEN command* 1-7 
SET MODULE/ALLOCATE command *9-2 
SET MODULE command• 1-17, 4-4, 4-19, CD-111 
SET OUTPUT command *2-8, CD-114 
SET PROMPT command*CD-116 
SET RADIX command *6-1, CD-117 
SET SCOPE command* 1-18, 4-2, 4-4, 4-11, 
4-20, 7-5, CD-119 

SET SEARCH command • 7-11, CD-122 
SET SOURCE command *7-2, CD-124 
SET STEP command *3-3, 7-7, CD-126 
SET TASK command*CD-129 
SET TERMINAL command *8-19, CD-132 
SET TRACE command • 1-13, 3-15, CD-134 
SET TYPE command *5-2, CD-139 
SET WATCH command* 1-14, 3-12, CD-142 
SET WINDOW command *8-11, CD-145 
Shareable image 

CANCEL IMAGE*CD-15 
debugging *4-23 
SET BREAK command*CD-90 
SET IMAGE*CD-102 
SET STEP command*CD-127 
SET TRACE command*CD-136 
SHOW IMAGE*CD-156 
SHOW MODULE command *4-19 
STEP command • CD-189 
/SHARE qualifier* 1-13, 4-19, CD-90, CD-136, 
CD-164, CD-189 
SHOW AST command*CD-147 
SHOW ATSIGN command • CD-148 
SHOW BREAK command*CD-149 
SHOW CALLS command* 1-11, 2-4, 3-19, CD- 
150 

SHOW DEFINE command • CD-151 
SHOW DISPLAY command• CD-I52 
SHOW EDITOR command• CD-I53 
SHOW EVENT_FACILITY command• CD-I54 
SHOW EXIT_HANDLERS command • 3-23, CD- 
155 

SHOW IMAGE command*CD-156 
SHOW KEY command *9-11, CD-157 
SHOW LANGUAGE command *2-6, CD-159 
SHOW LOG command *2-9, CD-160 
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SHOW MARGINS command • 7-14, CD-161 
SHOW MAX_SOURCE_FILES command• 7-16, 
CD-162 

SHOW MODE command • 6-1, CD-163 
SHOW MODULE command* 1-17, 4-19, CD-164 
SHOW OUTPUT command *2-8, CD-166 
SHOW RADIX command*CD-167 
SHOW SCOPE command* 1-18, 4-22, CD-168 
SHOW SEARCH command • 7-12, CD-169 
SHOW SELECT command*CD-170 
SHOW SOURCE command *7-3, CD-172 
SHOW STACK command*CD-174 
SHOW STEP command *3-3, CD-175 
SHOW SYMBOL/DEFINED command • CD-33 
SHOW SYMBOL command* 1-18, CD-176 
SHOW TASK command*CD-178 
SHOW TERMINAL command • 8-19, CD-181 
SHOW TRACE command • 3-15, CD-182 
SHOW TYPE command *5-2, CD-183 
SHOW WATCH command *3-13, CD-184 
SHOW WINDOW command • 8-11, CD-185 
/SILENT qualifier* 1-14, CD-90, CD-136, CD-142, 
CD-189 
Simple address 
defined* 5-3 
path-name prefix *5-4 
Simple symbol *4-7 
/SIZE qualifier*CD-49, CD-96 
Slash (/) 

division operator*5-10, D-6 
%SOURCE_SCOPE • 8-4, C-4 
Source directory 

displaying*7-3, CD-172 
search list *7-3, CD-21, CD-124 
source file in*7-2 
Source display* 1-8 

at breakpoint activation • 7-7 
at watchpoint activation • 7-7 
by address expression • 7-5 
by line number*7-5, CD-193 
by search string *7-10, CD-81 
by stepping*7-7 
discrepancies in *7-17 
display kind *8-15, C-1 
during program execution • 7-7 
line-oriented • 7-1 
margins in*7-13, CD-161 
next line*7-5 
not available* 1-8 
SRC, predefined • 8-4, C-4 
TYPE command* 1-9, CD-193 


Source file 

correct version of *7-3 
defined* 7-1 
file specification • 7-2 
location *7-1, CD-21, CD-124, CD-172 
maximum number*7-16, CD-108, CD-162 
/SOURCE qualifier*8-16, CD-59, CD-85, CD-90, 
CD-136, CD-142, CD-189 
EXAMINE command *7-6 
STEP command *7-7 
%SP* D-3 

SPAWN command*CD-186 
SRC source display *8-4, C-4 
SS$_DEBUG condition • D-1 
/START_POSITION qualifier • CD-98 
Statement number 

path-name prefix *5-5 
simple address *5-5 

/STATE qualifier*CD-39, CD-103, CD-158, CD- 
179 

/STATISTICS qualifier*CD-179 
STEP command* 1-10, 3-1, CD-188 

displaying default qualifiers for*3-3, CD-I75 
setting default qualifiers for*3-3, CD-126 
source display *7-7 
STOP command *2-13 
/STRING qualifier* 7-11, CD-82 
Symbol 

built-in *4-5, 5-7, C-5, D-3 
defining *4-6, CD-33 
displaying*CD-33, CD-176 
global *4-10 
line number*2-2 
local *2-2 

module setting* 1-17 
pointer-qualified • 4-9 
relation to path name* 1-10 
resolving *1-18, 4-9 
routine name*2-2 
simple *4-7 
/DEBUG qualifier* 2-2 
structure-qualified • 4-8 
subscript-qualified • 4-7 
types of *4-5 
Symbol declaration *4-9 
Symbolic mode*CD-109 
SYMBOLIZE command*CD-192 
/SYMBOL qualifier*CD-59 
Symbol record* 1-5 

deleting from RST • 1-17, 4-20 
DST • 4-2 
GST *4-3 

information in RST *4-19 
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Symbol record (cont'd.) 

inserting into the RST*1-17, 4-20 
RST *4-3 

traceback* 2-2, 4-1 
Symbol reference 
incorrect *4-4 
path name*4-11 
Symbol table 

used by debugger *4-2 
SYS$IMGST A • 2-4 

/SYSTEM qualifier* 1-13, CD-91, CD-137, CD-190 
System space 

SET BREAK command*CD-91 
SET STEP command*CD-127 
SET TRACE command*CD-137 
STEP command • CD-190 



TYPE command* 1-9, 7-5, CD-193 
Type conversion *6-12 
Type override*CD-25, CD-140, CD-183 
/TYPE qualifier*CD-42, CD-59, CD-176 



UNDEFINE/KEY command • 9-12, CD-196 
UNDEFINE command*CD-195 
/UP qualifier*CD-64, CD-74, CD-79 
/USE_CLAUSE qualifier*CD-177 


v 




%TASK* D-8 
Tasking 

SET TASK command*CD-129 
SHOW TASK command*CD-178 
/TASK qualifier*CD-42, CD-59 
/TEMPORARY qualifier*CD-91, CD-137, CD-143 
Terminal screen size 

displaying *8-19, CD-181 
%PAGE, % WIDTH symbols *C-6 
setting *8-19, CD-132 
/TERMINATE qualifier*CD-35 
Termination 

debugging session • CD-62, CD-76 
execution of handlers at *3-22 
/TIME_SLICE qualifier*CD-130, CD-179 
/TOP qualifier*CD-79 
Traceback*2-2, 4-1 

SHOW CALLS command* 1-11 
/TRACEBACK qualifier*4-1, 4-2 
Tracepoint 

canceling* CD-23 
defined* 1-13, 3-15 
delayed activation of*CD-134 
displaying *3-15, CD-182 
setting* 1-13, 3-15, CD-134 
Transfer address 

debugger activation • 2-4 
defined • 2-7 
execution at* 1-9, 3-5 
Truncation of ASCII data *6-12 
Type 

Data types and other types *5-1 


/VALUE qualifier*CD-32 
Variable name 

DEPOSIT command* 1-16 
EXAMINE command* 1-15 
SET WATCH command* 1-14 
VAX Language-Sensitive Editor*CD-50 
Verify 

SET OUTPUT command*CD-114 
% VISIBLE—T ASK • D-8 
/VISIBLE qualifier*CD-130 



/WAIT qualifier*CD-186 
Watchpoint 

canceling* CD-26 
defined* 1-14, 3-12 
displaying *3-13, CD-184 
restrictions *3-14 
setting* 1-14, 3-12, CD-142 
source display at *7-7 
WHEN clause 

effect with DO clause • 3-9 
example* 1-13 
format* CD-I 

WHILE command *9-6, CD-197 
% WIDTH • C-5 

/WIDTH qualifier*8-19, CD-132 
Window 

canceling • CD-27 
defined • 8-2 
identifying* CD-185 
predefined • C-7 
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Window (cont'd.) 

specifying • 8-10, CD-145 
WORD data type *5-2 
/WORD qualifier*CD-42, CD-59 
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